CD ROM Paradise Collection 4

home *** CD-ROM | disk | FTP | other *** search

/ CD ROM Paradise Collection 4 / CD ROM Paradise Collection 4 1995 Nov.iso / program / qbgps240.zip / GPS.DOC < prev next >

Wrap

Text File | 1995-01-11 | 132KB | 2,571 lines

Documentation for ┌───────────────────────────────────────────────────┐ │ GPS (General Purpose Subroutines) Library <v248> │ │ (c) Garry Spencer / Spencer Technologies │ │ P.O. Box 34OO9 Memphis, TN 38184-OOO9 │ └───────────────────────────────────────────────────┘ ┌───────────────┬─────────────────────────────────┐ │ Number of │ │ │ Functions in │ │ ├───────┬───────┤ │ │GPS.LIB│GPS.QLB│ Function Group │ ├───────┼───────┼─────────────────────────────────┤ │ 24 │ 24 │ Date / Time │ │ 18 │ 18 │ DOS (Handle-Based) │ │ 13 │ 13 │ File / Directory │ │ 8 │ 8 │ Joystick │ │ 25 │ 25 │ Keyboard │ │ 27 │ 27 │ Memory │ │ 17 │ 17 │ Mouse │ │ 22 │ 22 │ Numeric │ │ 22 │ 22 │ Screen (ANSI - text mode only) │ │ 32 │ 24 * │ Screen (VIDEO- text mode only) │ │ 36 │ 36 │ String │ │ 4 │ 4 │ System / Miscellaneous │ ├───────┼───────┼─────────────────────────────────┤ │ 248 │ 24O │ Total Number of Functions │ └───────┴───────┴─────────────────────────────────┘ * Note that the GPS.QLB quick-library does NOT support the following 8 routines: ColorPDQ, ColorQB, SetColorPDQ, SetColorQB, SetVideoSegPDQ, SetVideoSegQB, VideoSegPDQ and VideoSegQB. Warranty: None expressed or implied. The routines in this library have been thoroughly tested with Quick-BASIC version 4.5, HOWEVER Spencer Technologies and/or any employees of the company are not liable for the use or misuse of this software. The registered version of this software package is protected under the copyright laws of the United States of America. It must not be copied, transmitted or duplicated in any way. It is to be used only by the purchaser. INSTRUCTIONS FOR USING THE GPS LIBRARY WITH QUICK-BASIC The GPS library was designed solely for use with programs written in Quick-BASIC. Some of the routines may work with BASIC PDS or Visual-BASIC for DOS, however the testing of these routines was limited to programs written in Quick-BASIC version 4.5 ONLY. In some of the functions, CALLs were made to Quick-BASIC's internal routines such as B$ASSN etc. The GPS library was also tested with the PDQ (BASIC replacement) library from Crescent Software, 11 Bailey Ave., Ridgefield, CT O6877 (2O3-438-53OO). Their PDQ library replaces the BCOM45.LIB (and QB.LIB) libraries and creates .EXE files about one-half the size of normal Quick-BASIC executable files. Be sure to make a backup copy of the enclosed diskette (for your own use only). Note that capital O is used throughout this documentation in place of the slashed-zero (0). The GPS.QLB quick-library is designed to be used inside the Quick-BASIC editor/environment (e.g. QB progname /L GPS). Note that the GPS.QLB quick-library does NOT support the following 8 routines: ColorPDQ, ColorQB, SetColorPDQ, SetColorQB, SetVideoSegPDQ, SetVideoSegQB, VideoSegPDQ and VideoSegQB. The GPS.LIB library is designed to be used ONLY from the DOS command line. Note that each function and/or subroutine in the GPS.LIB library MUST be declared before it can be used. There is a file named GPS.BI which is included on the enclosed diskette. This file contains the correct DECLARE statement for each routine in GPS.LIB. To allow your programs to use this file, place the following statement in your source code (before any executable statements). '$Include: '\QB45\GPS.BI' Note that the single-quotes (') must be included as part of the statement. The \QB45 directory can be replaced with the appropriate directory name in which the GPS.BI file resides. If you wish to copy the individual DECLARE statements from the GPS.BI file to your source code, you should be extremely careful to use the BYVAL and SEG keywords wherever they appear. The under- score symbol (_) is used at the end of a line in Quick-BASIC to allow the program line to be continued on the next physical line in the file. Be sure to copy the entire DECLARE statement including continuation lines. To compile your program, type the following: BC progname/O; if you are not using ON ERROR GOTO/RESUME statements BC progname/O/E/X; if you are using ON ERROR GOTO/RESUME statements To link your program into an .EXE executable file, type: LINK/EX progname,,nul,\QB45\GPS; if you are linking with Quick-BASIC's BCOM45.LIB (assuming that the GPS.LIB file is in the \QB45 directory. You should obviously use the directory name in which the GPS.LIB file is located.) LINK/EX/NOD/NOE progname,,nul,\PDQ\PDQ \QB45\GPS; if you are using the PDQ.LIB library from Crescent Software (assuming that PDQ.LIB is located in the \PDQ directory) SPECIAL PROGRAMMING CONSIDERATIONS Many of the GPS functions use 16-bit (2-byte) integer values as operands or to return information to your program. Quick-BASIC's 2-byte integer variables (such as X%) use 16-bit signed values which have a range of -32768 to +32767. A 16-bit UNsigned integer can actually represent numbers in the range of O to +65535. There is a problem when using (%) type variables to represent numbers between +32768 and +65535. For example, the number used to represent the segment address of the text-mode memory area for a color monitor is 471O4. This number is obviously too large to be used in: X% = 471O4%. You must therefore, use another method of assigning the value 471O4 to the X% variable. The methods normally used for this purpose include representing these large values as hexadecimal numbers or as NEGATIVE numbers. To use hexadecimal: 471O4 is the same as B8OO (hex) X% = &HB8OO Note: Many scientific calculators can convert between decimal and hexadecimal. To convert large numbers in the range (+32768 to +65535) to negative values use: NegativeValue = LargeValue - 65536 For example, 471O4 - 65536 = -18432 X% = -18432% is the same as X% = &HB8OO Note: 65536 is too large to be used as a 2-byte integer in Quick-BASIC programs. If the conversion is to be calculated inside a program, use 65536& to allow the compiler to treat 65536 as a 4-byte (long) integer. To convert back from a negative value to a large positive value, use: LargeValue = NegValue + 65536 (ex. -18432 + 65536 = 471O4) The reason for the problem lies in the way Quick-BASIC uses a 16-bit (2-byte) number to represent signed values. The following diagram shows a 16-bit binary number. Each N represents a BIT which stands for (BInary-digiT). Each bit is either a one (1) or a zero (O) and is a power of two. 16384 4O96 1O24 256 64 16 4 1 N N N N N N N N N N N N N N N N 32768 8192 2O48 512 128 32 8 2 As you can see, if all bits are ON (i.e. equal to 1) the number would be: 1111111111111111 binary = FFFF (hexadecimal) --or-- 1+2+4+8+16+32+64+128+256+512+1O24+2O48+4O96+8192+16384+32768 = 65535 decimal HOWEVER, Quick-BASIC (and the 8Ox86) has designated the most-significant (leftmost) bit as the SIGN bit, so that it no longer means 32768 in signed 2-byte integers. If the sign bit is zero (O), the signed number is considered to be positive, therefore: O111111111111111 binary = 7FFF (hexadecimal) --or-- 1+2+4+8+16+32+64+128+256+512+1O24+2O48+4O96+8192+16384 = 32767 decimal If the sign bit is one (1), the signed number is considered to be negative, and is stored in 2s complement form. For example, 1111111111111111 = FFFF (hexadecimal) the sign bit is a one (1) therefore the number is negative and in 2s complement form. The number shown is -1 (in decimal). Convert from/to 2s complement form by complementing (inverting) all bits (1s complement), then add 1 to the result. SPECIAL PROGRAMMING CONSIDERATIONS (Continued) Segmented Memory Addressing Some of the microprocessors used in IBM-compatible computers (8O386+) can address all of the available memory space in a linear manner. The earlier processors (8O88, 8O86 etc) were designed to address memory in segments. The latest processors (Pentium etc.) can still be used to address memory which has been laid out in segments, therefore it is necessary to mention this method of memory access in this documentation. A typical segmented memory address has the following form: pppp:oooo where pppp is the paragraph (segment) and oooo is the offset within that segment. Note that both numbers are shown in 4-digit hexadecimal form. The actual memory address can be found by multiplying the paragraph by 16 (1O hex) and then adding the offset to that number. For example, segmented memory address 1742:4982 (hexadecimal) means that the paragraph is 1742 (hex) and the offset is 4982 (hex). Calculating the actual address, (1742 x 1O = 1742O) + 4982 = 1BDA2 (the actual address in hexadecimal) It is intuitively obvious to even the most casual observer, that each paragraph can only start on a memory location which is evenly divisible by 16. From that starting address, it is possible to address up to 64k (O to 65535) different memory locations (byte-wide). The accepted terminology, used in most literature, dictates that a paragraph of memory is 16 bytes long and that a segment of memory can be up to 64k (65536) bytes in length. Sometimes the terms paragraph and segment are used to represent the same thing, but it is usually apparent which meaning these terms have in context. To find the actual memory location of a variable, the Quick-BASIC commands VARSEG and VARPTR can be used. VARSEG finds the segment in which the variable resides and VARPTR finds the offset (pointer) from the start of that segment. Note that Quick-BASIC's default data segment is called DGROUP. A% = 1 MemSeg% = VARSEG ( A% ) 'find the segment in which A% resides MemPtr% = VARPTR ( A% ) 'find the offset (pointer) In this example, the variable (A%) is located at segment MemSeg% and at offset (pointer) MemPtr%. Please note that for each memory location, there are several combinations of segment and offset addresses which could point to that actual memory location. For example, 2415:OO11 is the same as 2416:OOO1 (in hexadecimal). It is possible to minimize the offset (pointer) by adding 1 to the segment while subtracting 16 (1O hex) from the offset. If this is done repeatedly, the offset can be reduced to the range (O to 15) or (O to F hex). This is exactly what the GPS library function MinimizePtr does. The function VarSegPtr also returns a minimized offset/segment combination for a given variable. If your program will be copying large blocks of memory, it would be best to minimize the offset (pointer) before using GPS functions like MemCopy etc. This will prevent a problem with overflow on the (DS:SI and/or ES:DI) internal registers. SPECIAL PROGRAMMING CONSIDERATIONS (Continued) Variable-Length Strings vs Fixed-Length Strings Many of the routines in the GPS.LIB library require a string as an operand. DO NOT use a fixed-length string for ANY of these operands (arguments). The reason for this is that Quick-BASIC stores these two string types differently. A fixed-length string is basically a block of memory which can either reside in DGROUP (default data segment) or in the far heap (outside DGROUP). A Quick-BASIC variable-length string, such as X$, must reside in DGROUP. In order to keep the assembly language code size small, it was assumed that all string operands were variable-length ($) string types. A quoted string, like "text string" is also stored (as a constant) in variable-length string format, so that this type can also be used as an operand. Note that some routines actually change the operand string directly (e.g. UpperCase). For these routines you should NOT use a quoted string constant, such as "Text". An example of each string type is given below: DIM TXT AS STRING*5O TXT is a fixed-length string and should NEVER be used as a string operand. The statement: Call UpperCase ( TXT ) would therefore be illegal. "The quick brown fox" is a quoted string which is stored like a variable-length string and can be used as a string operand for MOST but not all routines. This string type may NOT be used in routines which change the string directly, such as ChgMid, LowerCase, Replace, and UpperCase. TextString$ is a variable-length string which can be used as an operand in ANY of the GPS.LIB routines. Note that a fixed-length string can be used to receive the return value of a string function. For example, the following program code is correct: DIM TXT AS STRING*34 TXT=FindFile$ ( O, "*.BAS", 7) SPECIAL PROGRAMMING CONSIDERATIONS (Continued) A Quick-BASIC variable-length string is stored in the following manner: ┌──────┬──────┬──────┬──────┐ │ Length │ Location │ └──────┴──────┴──────┴──────┘ └─────────────┬─────────────┘ │ This is a 4-byte string descriptor for a variable-length string. The string descriptor is made up of 2 bytes for the string length and 2 bytes for the location (offset within the DGROUP segment) of the first byte of the actual string data. ┌──────┬──────┬──────┬──────┬──────┬──────┬──────┬──────┬──────┬──────┬─∙∙∙∙∙ │ Back Pointer│ Actual string data would be placed here ..... └──────┴──────┴──────┴──────┴──────┴──────┴──────┴──────┴──────┴──────┴─∙∙∙∙∙ The back pointer (which ALWAYS immediately precedes the actual string data in memory) points to the memory location of the first byte of the string descriptor (shown above). The back pointer is used by Quick-BASIC to allow clean-up of the string data area. Quick-BASIC examines the back pointers and each back pointer allows Quick-BASIC to find the string descriptor belonging to the back pointer's accompanying string data. If the string descriptor (pointed to by a back pointer) no longer points to the actual string data, then Quick-BASIC knows that the memory block occupied by the string data can be reclaimed for other strings etc. The 64k-byte DGROUP segment, which holds the string descriptor, the back pointer and the actual string data, can be determined by the following statement. DGROUP% = VARSEG(TextString$) The location of the first byte of the string descriptor is found as follows: StrDesc% = VARPTR(TextString$) The location of the first byte of the actual string data is found by: StrData% = SADD(TextString$) The following program code shows how to access each part of the string (TextString$). DGROUP% = VARSEG(TextString$) 'finds the default data segment DGROUP DEF SEG = DGROUP% 'make PEEKs/POKEs use DGROUP segment StrDesc% = VARPTR(TextString$) 'finds address of 1st byte of string descriptor Length% = 256% * PEEK(StrDesc%+1) + PEEK(StrDesc%) StrData% = SADD(TextString$) 'finds address of 1st byte of actual string data StrData% = 256% * PEEK(StrDesc%+3) + PEEK(StrDesc%+2) 'another way to find it BackPtr% = StrDesc% 'the same for an active string (address of descriptor) BackPtr% = 256% * PEEK(StrData%-1) + PEEK(StrData%-2) 'another way to find it Note: The back pointer itself (BackPtr%) holds the ADDRESS (within DGROUP) of the first byte of the string descriptor. SPECIAL PROGRAMMING CONSIDERATIONS (Continued) Text Screen Color Attribute Byte The screen subroutines and functions, in the GPS library, are to be used in text-mode only (SCREEN O). These routines use direct video memory writes to update the screen. You will notice that some of these routines require a color attribute byte operand. The format for this byte is as follows (shown as an 8-bit binary number): Blink Bit High-Intensity (Bright) Bit │ │ ┌─┴─┐ ┌─┴─┐ N N N N N N N N └───────┬───────┘ └──────────┬──────────┘ │ │ Background Color Foreground color ( O to 7 ) ( O to 7 for normal ) ( 8 to 15 for bright ) The basic colors are: O = black 8 = dark gray 1 = blue 9 = bright blue 2 = green 1O = bright green 3 = cyan 11 = bright cyan 4 = red 12 = bright red 5 = magenta (purple) 13 = bright magenta (purple) 6 = brown 14 = bright yellow 7 = white / gray 15 = bright white Note: The Quick-BASIC command: COLOR foreground,background uses numbers 16 to 31 as blinking foreground colors. (16 + foreground) You can use the GPS library function ColorAttr% to calculate the value of the attribute byte. If Foreground% represents Quick-BASIC's foreground color (O to 31) and Background% represents the background color (O to 7), then the following line of code will calculate the correct color attribute byte. ColorAttributeByte% = ColorAttr% ( Foreground% , Background% ) If the value of a color attribute byte is known, and you wish to separate it into separate foreground and background colors, use the following command: Call AttrColor ( ColorAttributeByte% , Foreground% , Background% ) -----or the alternate form of calling a subroutine----- AttrColor ColorAttributeByte% , Foreground% , Background% SPECIAL PROGRAMMING CONSIDERATIONS (Continued) Special Note: Quick-BASIC version 4.5 supports the use of alphanumeric labels. It is no longer necessary to use line numbers. This is good news for programmers, however it can cause a minor problem when using external subroutines such as the ones in the GPS library. Here is the problem: There are two ways to call a subroutine in Quick-BASIC. The first method is to use the CALL keyword and enclose the operands (if any) in parentheses. For example, Call NumLockOff Call AttrColor(Attr%,Fore%,Back%) The second method of calling these subroutines is to simply use the name of the subroutine followed by the operands (no parentheses). NumLockOff AttrColor Attr%,Fore%,Back% Both of these methods work, but since Quick-BASIC allows multiple statements per line by using a colon (:) and it also uses the colon (:) at the end of an alphanumeric label, Quick-BASIC can sometimes get confused if you use the second method of calling a subroutine (with no operands) and try to place another statement on the same line using a colon (:). For example, NumLockOff : Call AttrColor(Attr%,Fore%,Back%) Quick-BASIC will think that NumLockOff is a label even though there is a space between it and the colon (:). This is a problem even when the subroutine has been previously declared. You should either put NumLockOff on a separate line or use the Call NumLockOff format. This is a minor problem that only occurs if the subroutine has no operands. Special Note: In an attempt to keep code size small, error checking on operands (e.g. screen row and column) was kept to a minimum. If the documentation shows the limits on a particular function, your calling program should make sure that no out-of-bounds operands are supplied to the functions. SPECIAL PROGRAMMING CONSIDERATIONS (Continued) USING THE ALIAS KEYWORD IN A DECLARE STATEMENT The ALIAS keyword allows you to substitute the name of one of Quick-BASIC's internal functions/subroutines in the place of your routine. This is necessary in most cases because many of Quick-BASIC's internal routines use the ($) dollar-sign or the (_) underscore in the function name. For example, pass an an ERRORLEVEL to DOS on exit from your program. The DECLARE tells Quick-BASIC to substitute _exit for the EndERRLevel statement. '------------------------------------------------------------------------------ 'In Quick-BASIC use this: DECLARE SUB EndERRLevel ALIAS "_exit" (BYVAL ErrorLevel%) EndERRLevel 15 'this would end your program and also pass the number 15 'to DOS as the ERRORLEVEL variable which could then be 'tested in a batch file with the IF ERRORLEVEL statement 'Note: This particular routine (_exit) will only work when compiled to an .EXE file from the command line. '------------------------------------------------------------------------------ '------------------------------------------------------------------------------ 'In PDQ you MUST use PDQ's ErrLevel Statement (no alias) DECLARE SUB ErrLevel (ErrorLevel%) EndLevel 15 'this would end your program and also pass the number 15 'to DOS as the ERRORLEVEL variable which could then be 'tested in a batch file with the IF ERRORLEVEL statement '------------------------------------------------------------------------------ Some additional examples are shown below: DECLARE SUB FileRead ALIAS "B$GET4" (BYVAL FileNum%, BYVAL FilePosition&, _ BYVAL MemSegment%, BYVAL MemOffset%, _ BYVAL NumberOfBytes%) DECLARE SUB FileWrite ALIAS "B$PUT4" (BYVAL FileNum%, BYVAL FilePosition&, _ BYVAL MemSegment%, BYVAL MemOffset%, _ BYVAL NumberOfBytes%) OPEN "Test.Dat" FOR BINARY AS BASICFileNumber% FileRead BASICFileNumber%,FilePosition&,MemSegment%,MemOffset%,NumberOfBytes%) FileWrite BASICFileNumber%,FilePosition&,MemSegment%,MemOffset%,NumberOfBytes%) These two routines will read-from/write-to a file opened in BINARY mode. Data is transferred directly between the file and memory (segment:offset). ┌─────────────────────────────────────────────────────────────────────────────┐ │ DATE / TIME FUNCTIONS │ └─────────────────────────────────────────────────────────────────────────────┘ FUNCTION: DayOfWeek% (AnyDate$) Returns the day of the week (O=Sunday ... 6=Saturday) for the specified date in MM-DD-YYYY form. Note: MM is month (1 to 12), DD is day (1 to 31) and YYYY is the year (198O to 21O7). The date must be on or after O1-O1-198O. If an incorrect date is specified, the program will be halted by "Illegal Function Call" caused by BASIC's (B$SDAT routine). example: Day%=DayOfWeek%("12-31-1999") FUNCTION: DayStr$ (WkDay%) Returns a string containing the day of the week specified by WkDay% (O to 6). example: A$=DayStr$(O) 'A$ would be "Sunday" (note the mixed case) A$=DayStr$(6) 'A$ would be "Saturday" FUNCTION: DayWeek% (Mon%, Day%, Year%) Returns the day of the week (O=Sunday ... 6=Saturday) for the specified date. Note: Do not use MONTH% as a variable. The year must be in the range 198O to 21O7. If an incorrect date is specified, the function will return -1 (error). example: DWeek% = DayWeek%(12,31,1999) Note: If you need to use a year outside 198O to 21O7, then use the WeekDay% function. FUNCTION: EventDone% Checks the status of the last EventSet subroutine call. If EventDone% is zero, it means the event timer is still running. If it is equal to -1, it signals that the timer has finished its timed interval. (see EventSet subroutine) SUBROUTINE: EventSet Microseconds& Starts the event timer with a value in microseconds. The status of the event can be checked using the EventDone% function. For example: (note: 1 microsecond = 1 millionth of a second) EventSet 1OOOOO& '1OOOOO microseconds is the same as .1 sec While Not EventDone% 'your statements here will continuously execute for .1 seconds Wend SUBROUTINE: EventWait Microseconds& Starts the event timer with a value in microseconds. This routine differs from EventSet in that EventWait does not return to the calling program until the event timer interval has elapsed. example: EventWait 5OOOOO& 'wait here for one-half second SUBROUTINE: GetDate Mon%, Day%, Year%, DWeek% Returns the month, day, year and day-of-week into the specified variables. Notes: For DWeek% O=Sunday ... 6=Saturday Do not use MONTH% as a variable. example: GetDate MM%,DD%,YY%,DWk% SUBROUTINE: GetTime Hrs%, Min%, Sec%, HSec% Returns the hours (O to 23), minutes, seconds and hundredths-of-seconds into the specified variables. Note: The time is only updated 18.2 times per second. example: GetTime HH%,MM%,SS%,S1OO% SUBROUTINE: Hibernate TickVal% Causes program execution to pause for a length of time equal to the specified number of timer ticks. Key presses are ignored during the paused state. Note: There are approximately 18.2 timer ticks in one second. example: Hibernate 91% 'pause for 5 seconds FUNCTION: LongDate$ (Date2Byte$) Expands a previously compressed 2-byte date string into a 1O-byte date string with the form MM-DD-YYYY (month-day-year). This function should only be used with the ShortDate$ function. NO error checking is performed on the date! FUNCTION: LongTime$(TwoByte$) Expands a previously compressed 2-byte time string into a 5-byte time string with the form HH:MM (24-hour format). This function should only be used with the ShortTime$ function. NO error checking is performed on the time! FUNCTION: MonthStr$ (MonthVal%) Returns a string containing the month name specified by MonthVal% (1 to 12). example: A$=MonthStr$(1) 'A$ would be "January" (note the mixed case) A$=MonthStr$(12) 'A$ would be "December" FUNCTION: SetDate% (Mon%, Day%, Year%) Sets the current date to the specified month, day and year. Note: Do not use MONTH% as a variable. The year must be in the range of 198O to 21O7. This function returns zero if the specified date is valid, otherwise it returns -1 (error). example: X%=SetDate%(12,31,1999) 'sets date to 12-31-1999 'X%=O if o.k. X%=-1 if error FUNCTION: SetTime% (Hrs%, Min%, Sec%, HSec%) Sets the current time to the specified hours (O to 23), minutes, seconds and hundredths-of-seconds. This function returns zero if the specified time is valid, otherwise it returns -1 (error). example: X%=SetTime%(23,45,33,25) 'sets time to 23:45:33.25 'X%=O if o.k. X%=-1 if error FUNCTION: ShortDate$ (AnyDate$) Compresses the given 1O-byte date string (MM-DD-YYYY form) into a 2-byte string which can then be stored in a file etc. The 2-byte resultant string can be used in a chronological sort routine. This function should be used with with the LongDate$ function. NO error checking is performed on the date. example: SDate$=ShortDate$("12-31-1999") LDate$=LongDate$(SDate$) FUNCTION: ShortTime$ (Time24$) Compresses the given 5-byte time string (HH:MM 24-hour format) into a 2-byte string which can then be stored in a file etc. The 2-byte resultant string can be used in a chronological sort routine. This function should be used with the LongTime$ function. NO error checking is performed on the time. example: STime$=ShortTime$("23:59") LTime$=LongTime$(STime$) FUNCTION: Snooze% (TickVal%) Causes program execution to pause for a length of time equal to the specified number of timer ticks or until a key is pressed. This function has a return value equal to the keycode (if any) used to prematurely end the delay. See the keycode table in the appendix. Note: There are approximately 18.2 timer ticks in one second. example: X%=Snooze%(91%) 'pause for 5 seconds or until a key is pressed FUNCTION: TickTime$ (TickValue&) This function converts the specified number of timer ticks (TickValue&) into an 8-byte time string in HH:MM:SS form. (note: HH = OO to 23) There are approximately 18.2 timer ticks in one second and approximately 1O92 ticks in one minute. The maximum number of ticks in one day is 1573O39. example1: T$=TickTime$(Timr&) 'uses Timr& function and would return the same 'string as BASIC's TIME$ function. example2: TLimit&= (15& * 1O92&) 'time limit is 15 minutes TimerReset 3 'reset timer#3 Temp: TRemain& = TLimit& - TimerRead&(3) 'calculate time remaining If TRemain& <= O GoTo Quit Locate 1,1 : Print TickTime$(TRemain&) 'print countdown time GoTo Temp Quit: 'continue program here after time has expired FUNCTION: TimerRead& (TimerNumber%) SUBROUTINE: TimerReset TimerNumber% TimerRead& returns the number of timer ticks since the specified TimerNumber% was reset (using the TimerReset subroutine). The TimerNumber% should be in the range (O to 15). If the TimerReset subroutine is called, with a TimerNumber% outside the range (O to 15), then ALL 16 timers (O to 15) will be reset to zero. There are approximately 18.2 timer ticks in one second. example: TimerReset -1 'reset ALL 16 timers to zero TimerReset 16 'reset ALL 16 timers to zero TimerReset O 'reset only timer number O to zero TimerReset 15 'reset only timer number 15 to zero TMRO&= TimerRead&(O) 'TMRO& set to number of ticks since timer O was reset TMR15&=TimerRead&(15) 'TMR15& set to number of ticks since timer 15 was reset Note: Attempting to read outside the range (O to 15) will return unpredictable values. These routines correctly handle the timer tick "roll-over" at midnight, but each timer will only be valid for up to 24 hours after it is reset to zero. FUNCTION: TmrRd& ( TimerVariable&) SUBROUTINE: TmrRst TimerVariable& These routines are basically the same as the TimerRead& and TimerReset routines, except that a long-integer variable is used to store the timer value instead of using an internal storage area. This allows an essentially unlimited number of timers to be used. example: TmrRst TimerVar& While TmrRd&(TimerVar&)<1OO : Wend 'wait here for 1OO timer ticks FUNCTION: Timr& Returns the number of timer ticks since midnight. Note: There are approximately 18.2 timer ticks in one second. example: Ticks& = Timr& 'this returns a long integer FUNCTION: WeekDay% (Mon%, Day%, Year%) This function is identical to the DayWeek% function except that it accepts any year in the range (1582 A.D. to 245O A.D.). The reason that these two functions (DayWeek% and WeekDay%) are both included in this library, is that the WeekDay% is a bit larger than DayWeek% and should only be used when a year outside the 198O to 21O7 range is to be specified. This function returns O=Sunday...6=Saturday, and it returns -1 if an error occurs (i.e. illegal date). example: A%=WeekDay%(7,4,1776) 'A% is the day of the week on which the 'Declaration of Independence was signed 'on July 4, 1776. ┌─────────────────────────────────────────────────────────────────────────────┐ │ DOS (Handle-Based) FUNCTIONS │ └─────────────────────────────────────────────────────────────────────────────┘ The routines in this section use the standard DOS services to access files. When a file is opened, using the DOSOpen routine, DOS assigns a unique "handle" to that file. Note: This handle number is --NOT-- the same thing as BASIC's file number! Your program must keep track of the handle number after a file is opened. The DOSRtnErr% function must be DECLAREd in your program (or '$include: 'gps.bi') because it is the only way to determine if an error occurred during execution of any of the GPS library DOS routines. Note: ALL of the GPS library DOS routines modify the DOSRtnErr% value (except, of course, the DOSRtnErr% routine itself). SUBROUTINE: DOSClose Handle% This routine closes the file belonging to the specified handle. ex: DOSOpen "Temp.Fil",O,1,Handle% DOSClose Handle% SUBROUTINE: DOSDel FileName$ This routine deletes the specified file. Note that this routine uses the actual filename instead of a handle. ex: DOSDel "Temp.Fil" FUNCTION: DOSFAttr% (FileName$) Returns the DOS File Attribute byte value for the specified file. The bit values of this byte are as follows: Bit O - Binary Value= 1 - Read_Only File Bit 1 - Binary Value= 2 - Hidden File Bit 2 - Binary Value= 4 - System File Bit 3 - Binary Value= 8 - Volume Name Bit 4 - Binary Value= 16 - Directory Name Bit 5 - Binary Value= 32 - Archive Bit Bit 6 - Binary Value= 64 - <reserved> Bit 7 - Binary Value= 128 - <reserved> Note that this function uses the actual filename instead of a handle. ex: Attributes% = DOSFAttr% ("Temp.Fil") 'get the attributes for a file SUBROUTINE: DOSFAttrSet FileName$, AttributeByte% Sets the DOS File Attribute Byte for the specified file using the value of AttributeByte%. See the DOSFAttr% function for a description of this byte. Note that this subroutine uses the actual filename instead of a handle. ex: Attributes% = DOSFAttr% ("Temp.Fil") DOSFAttrSet "Temp.Fil", (Attributes% OR 1) 'make the file read-only SUBROUTINE: DOSFDateGet Handle%, Mon%, Day%, Year%, Hr%, Min%, Sec% This routine retrieves the date and time for the file whose handle is specified. Note: The 24-hour system is used for Hr% (i.e. OO to 23). ex: DOSOpen "Temp.Fil",O,1,Handle% DOSFDateGet Handle%,Month%,Day%,Year%,Hour%,Minute%,Second% DOSClose Handle% SUBROUTINE: DOSFDateSet Handle%, Mon%, Day%, Year%, Hr%, Min%, Sec% This routine sets the date and time for the file whose handle is specified. Note: The 24-hour system is used for Hr% (i.e. OO to 23). The seconds must be an even number. The year must be 198O or later. ex: DOSOpen "Temp.Fil",O,1,Handle% DOSFDateGet Handle%,Month%,Day%,Year%,Hour%,Minute%,Second% DOSFDateSet Handle%,Month%,Day%,Year%,O,O,O 'set file time to midnight OO:OO DOSClose Handle% 'Note: The DOSFDateGet routine was used first because it was necessary ' in order to preserve the month, day and year. FUNCTION: DOSFPtr& (Handle%) This routine retrieves the file pointer for the file whose handle is specified. The file pointer is the place in the file where the next file read or write would occur. Note that the beginning of the file is at pointer value=O. ex: FilePointer& = DOSFPtr&(Handle%) : Print FilePointer& SUBROUTINE: DOSFPtrMove Handle%, PtrMovement& This routine moves the file pointer by the number of bytes specified by PtrMovement& for the file whose handle is specified. If PtrMovement& is positive then the movement is forward. If PtrMovement& is negative then the movement is backwards. Note that the beginning of the file is at pointer value=O. ex: DOSFPtrMove Handle%, 16 'move file pointer forward by 16 bytes DOSFPtrMove Handle%,-12 'move file pointer backwards by 12 bytes SUBROUTINE: DOSFPtrSet Handle%, NewPtr& This routine sets the file pointer to the position specified by NewPtr& for the file whose handle is specified. Note that the beginning of the file is at pointer value=O. ex: DOSFPtrSet Handle%,O 'set the pointer to the beginning of the file FileSize&=DOSFSize&(Handle%) DOSFPtrSet Handle%,FileSize& 'set the pointer to the end of the file 'for append mode operation FUNCTION: DOSFSize& (Handle%) Returns the file size of the file whose handle is specified. ex: DOSOpen "Temp.Fil",O,1,Handle% FileSize& = DOSFSize&(Handle%) DOSClose Handle% SUBROUTINE: DOSOpen FileName$, ReadWrite%, InitPtr%, Handle% Opens the specified file and assigns its handle to the Handle% variable. The ReadWrite% value should be specified as O=read-only, 1=write-only and 2=read-write. The InitPtr% should be specified to instruct DOS where the DOS file pointer should be positioned for this file, O=truncate file to zero length (only if ReadWrite%>O), 1=point to beginning of file and 2=point to end of file. ex: DOSOpen "Temp.Fil",O,1,Handle% 'opens the file as read-only and points to the beginning of the file 'and assigns its handle to the Handle% variable SUBROUTINE: DOSRdMem Handle%, MSeg%, MPtr%, NBytes% SUBROUTINE: DOSRdStr Handle%, Text$, NBytes% SUBROUTINE: DOSRdVar Handle%, AnyVariable, NBytes% These routines read data from the file, whose handle is specified, starting at the current position of the file pointer. The first form (DOSRdMem) reads the specified number of bytes, from the file, into the segmented memory address MSeg%:MPtr%. The second form (DOSRdStr) reads the specified number of bytes, from the file, into a variable-length string variable Text$. The third form (DOSRdVar) reads the specified number of bytes, from the file, into a normal variable or a TYPE variable. ex: DOSRdMem Handle%,&hB8OO,O,4OOO 'reads a 4OOO-byte screen image into the 'color (text) video memory segment from file DOSRdStr Handle%,XYZ$,123 'reads 123 bytes into the XYZ$ string from file DOSRdVar Handle%,A%(O),9O 'reads 45 values (2 bytes each) into integer 'array A%() from file 'note: array must first be dimensioned FUNCTION: DOSRtnErr% Returns zero if the last GPS library DOS routine did not result in an error, otherwise the actual DOS error number is returned. ex: DOSOpen "FileName.Ext",O,1,Handle% ErrorInDOS% = DOSRtnErr% If ErrorInDOS%<>O Then Print "DOS Error Number ";ErrorInDOS% : Goto Halt SUBROUTINE: DOSWrtMem Handle%, MSeg%, MPtr%, NBytes% SUBROUTINE: DOSWrtStr Handle%, Text$ SUBROUTINE: DOSWrtVar Handle%, AnyVariable, NBytes% These routines write data to the file, whose handle is specified, starting at the current position of the file pointer. The first form (DOSWrtMem) writes the specified number of bytes, to the file, from the segmented memory address MSeg%:MPtr%. The second form (DOSWrtStr) writes the contents of the variable-length string Text$ to the file. The third form (DOSWrtVar) writes the specified number of bytes, to the file, from a normal variable or a TYPE variable. ex: DOSWrtMem Handle%,&hB8OO,O,4OOO 'writes a 4OOO-byte screen image from the 'color (text) video memory segment to file DOSWrtStr Handle%,XYZ$ 'writes the XYZ$ string to the file (no cr-lf added) DOSWrtVar Handle%,A%(O),9O 'writes 45 values (2 bytes each) from integer 'array A%() to file 'note: array must first be dimensioned ┌─────────────────────────────────────────────────────────────────────────────┐ │ FILE / DIRECTORY FUNCTIONS │ └─────────────────────────────────────────────────────────────────────────────┘ SUBROUTINE: ChgDir NewDir$ Changes the default directory to the one specified. If the drive is different from the current drive, it is also changed. Note: BASIC's CHDIR command will not change the default drive. example: ChgDir "A:" 'changes ONLY the drive ChgDir "A:\" 'changes the drive and directory FUNCTION: CurrentDir$ Returns the current default directory including drive. example: ChgDir "C:\" A$=CurrentDir$ ChgDir "\TEMP" B$=CurrentDir$ Print A$,B$ result: C:\ C:\TEMP FUNCTION: DirExist% (FileName$) Returns -1 if the specified directory exists and returns zero (O) if it doesn't. Note: If a critical error occurs (drive door open etc.) the critical error message (Abort - Retry - Fail) will still appear on the screen. Exist%=DirExist%("C:\TEMP") FUNCTION: DriveDir$ (Drive%) Returns the current default directory on the specified drive: O=current drive 1=A: 2=B: 3=C: etc. example: A$=DriveDir$(3) print A$ result: C:\TEMP FUNCTION: FileExist% (FileName$) Returns -1 if the specified file exists and returns zero (O) if it doesn't. Note: If a critical error occurs (drive door open etc.) the critical error message (Abort - Retry - Fail) will still appear on the screen. Exist%=FileExist%("C:\TEMP\MISC.DAT") SUBROUTINE: FileToMem FileNum%,MemSeg%,MemAdr%,NumBytes% Copies the specified number of bytes (NumBytes%) from a file (at the current file pointer location) directly into memory at paragraph (MemSeg%) and offset (MemAdr%). The FileNum% is BASIC's file number (not the file handle). The file must already be opened in Binary Access Read mode. example: 'Copy 4OOO bytes from the beginning of a file to video memory Open "Temp.SCN" for Binary Access Read as #1 FileToMem 1,&HB8OO,O,4OOO : Close#1 SUBROUTINE: FileToVar FileNum%,Variable,VariableSize% Copies the specified number of bytes (VariableSize%) from a file (at the current file pointer location) directly into memory at the location of the specified Variable. The FileNum% is BASIC's file number (not the file handle). The file must already be opened in Binary Access Read mode. This routine is handy for reading from a file directly into a TYPE variable. ex: TYPE NewVar:First as Integer:Second as Integer:END TYPE:Dim Temp as NewVar Open "Temp.TMP" for Binary Access Read as #1 FileToVar 1,Temp.First,4 : Close#1 'reads both 2-byte integers FUNCTION: FindFile$ (First%,Search$,AttrMask%) Returns a 34-byte directory string containing information about the file(s) specified in the Search$ string. The First% operand must be zero (O) for the first function call to this routine and non-zero for all subsequent calls (with the same Search$ and AttrMask% specification). If a different search criteria specification is given (later in the program) then First% must again be set to zero for the first call and non-zero for subsequent calls. This is due to the fact that the DOS call used here must set up the DTA area on the first call. Additional calls, using a non-zero First% value, will use the DTA area previously defined. The Search$ operand can be any valid file specification including directory names, wildcards etc. Please note that the 11-byte filename RETURNED by this function will NOT include its directory name. The AttrMask% tells DOS which types of files to include in the search. Normal files (non-directory, non-volume label, non-hidden etc.) are ALWAYS included except when bit 3 (binary value 8) is set. See the example for bit meanings. The 34-byte FindFile$ string returned by this function has the following form: ┌─filename in FILENAMEEXT form (no path/directory name returned for the file) │ ┌─filesize in 1O-byte string form │ │ ┌─file date in YYYYMMDD form (YYYY=year MM=month DD=day) │ │ │ ┌─file time in HHMM (24hr) form ├─────────┐├────────┐├──────┐├──┐┌─file attribute byte FILENAMEEXT2147483647199912312359# FindFile$ returns a null ("") string when no more files are found. Note: The filesize is returned as a 1O-byte string. It was possible to return a 4-byte (compressed) value thus saving 6 bytes, however most programmers would want to print this field directly or use it in a sort routine, therefore it was decided to put it in printable form in the return string. The FindFileS subroutine (on the next page) is a shortened version of this routine. Example: Find first file matching *.* specification F$=FindFile$(O,"*.*",7) FileName$=Left$(F$,8)+"."+Mid$(F$,9,3) 'FileName$ converts FILENAMEEXT form to FILENAME.EXT form FSize$=Mid$(F$,12,1O) 'FSize$ is the file size in 1O-byte string form (handy for sorting/printing) 'could also use FSize$=Right$(Mid$(F$,12,1O),NumDigits%) to shorten string FDate$=Mid$(F$,26,2)+"-"+Mid$(F$,28,2)+"-"+Mid$(F$,22,4) 'FDate$ converts YYYYMMDD form to MM-DD-YYYY form Time24$=Mid$(F$,3O,2)+":"+Mid$(F$,32,2) 'Time24$ converts HHMM to HH:MM (24hr) form FAttr%=AscMid%(F$,34) 'FAttr% uses GPS library function AscMid% to get the file attribute byte: 'bit O binary value 1 = read-only 1 2 = hidden 2 4 = system 3 8 = volume ID 4 16 = directory SUBROUTINE: FindFileS First%,Search$,AttrMask%,TypeVariable This subroutine is identical to the FindFile function except that a shorter (2O-byte) string is returned INTO the specified TypeVariable. This shorter string is useful if a large list of files (and file info) is to be stored in memory. The following program code shows how to define and use the TypeVariable. This routine requires more work in uncompressing the DTA-format-information than the FindFile function does. Type DirVar FileName as String*8 FileExt as String*3 Attribute as String*1 FTime as Integer FDate as Integer FSize as Long End Type Dim Dir as DirVar '---Dir is now a variable of Type DirVar FindFileS O,"*.*",7,Dir 'for first try use First%=O FindFileS -1,"*.*",7,Dir 'for subsequent tries use non-zero First% The Dir.Attribute is set to ASCII 255 when no more files are found. 'after the FindFileS subroutine is executed, the following variables 'are available for use in your program: 'Dir.FileName is the filename as an 8-byte fixed-length string 'Dir.FileExt is the extension as a 3-byte fixed-length string Name$ = RTRIM$(Dir.FileName) : Ext$ = RTRIM$(Dir.FileExt) If Ext$<>"" Then Name$=Name$+"."+Ext$ 'Dir.Attribute is a 1-byte fixed-length string representing the file's attribute ' byte (use BASIC's ASC function to get its integer value) FileAttr% = ASC(Dir.Attribute) 'Dir.FTime is the file time as a 16-bit integer (DTA format) ' Note: Dir.Time is a SIGNED integer - be careful when sorting by time ' x x x x x x x x x x x x x x x x ' └─┬───────────────┘ └───┬─────────────────┘ └──┬──────────────┘ ' Hours (O to 23) Minutes (O to 59) Seconds in 2sec intervals FileTime% = Dir.FTime '---or--- FileTime% = ShiftRight%(Dir.FTime,5) 'to use in sort routines 'Dir.FDate is the file date as a 16-bit integer (DTA format) ' x x x x x x x x x x x x x x x x ' └─┬───────────────────────┘ └─┬───────────┘ └─┬───────────────┘ ' Year - 198O (offset) Month (1 to 12) Day (1 to 31) FileDate% = Dir.FDate 'Dir.FSize is the file size as a 4-byte (long) integer FileSize& = Dir.FSize SUBROUTINE: MemToFile FileNum%,MemSeg%,MemAdr%,NumBytes% Copies the specified number of bytes (NumBytes%) from memory at paragraph (MemSeg%) and offset (MemAdr%) into the file (at the current file pointer location) whose BASIC file number (FileNum%) is specified. The file must already be opened in Binary mode. Note: The BASIC file number is not the same thing as the DOS file handle number. example: 'Copy 4OOO bytes from video memory to a file Open "Temp.SCN" for Output as #1 : Close#1 'this resets filesize to O if needed Open "Temp.SCN" for Binary as #1 MemToFile 1,&HB8OO,O,4OOO : Close#1 FUNCTION: StartUpDir$ Returns the directory containing the currently running .EXE file. This is handy for accessing data files associated with the current program. Note that the directory ALWAYS ends with a backslash (\). This allows easy concatenation of filenames to the directory name. If you need to perform a CHDIR to the start up directory then you must remove the (\) from the directory names other than the root directory. example: SDir$=StartUpDir$ 'SDir$ would have the general form C:\ (root directory) or C:\TEMP\MISC\ DataFile$=SDir$+"Temp.Dat" If LEN(SDir$)=3 then CHDIR SDir$ else CHDIR LEFT$(SDir$,LEN(SDir$)-1) FUNCTION: StartUpExec$ Returns the name of the currently running .EXE executable file. This can be used to access data which has been added to the end of an .EXE file. e.g. COPY/B TEMP.EXE+DATA.FIL PROGRAM.EXE example: SExec$=StartUpExec$ Open SExec$ for Input as #2 Seek#2,EXEFileSize&+1 'EXE filesize (without added data) must be known '....retrieve data here.... SUBROUTINE: VarToFile FileNum%,Variable,VariableSize% Copies the specified number of bytes (VariableSize%) from memory at the location of the Variable into the file (at the current file pointer location) whose BASIC file number (FileNum%) is specified. The file must already be opened in Binary mode. Note: The BASIC file number is not the same thing as the DOS file handle number. This routine is handy for writing from a TYPE variable directly into a file. ex: TYPE NewVar:First as Integer:Second as Integer:END TYPE:Dim Temp as NewVar Open "Temp.SCN" for Output as #1 : Close#1 'resets filesize to O if needed Open "Temp.TMP" for Binary Access as #1 VarToFile 1,Temp.First,4 : Close#1 'writes both 2-byte integers ┌─────────────────────────────────────────────────────────────────────────────┐ │ JOYSTICK FUNCTIONS │ └─────────────────────────────────────────────────────────────────────────────┘ FUNCTION: JoyStkAX% Returns the X (horizontal) value of Joystick A. example: JAX%=JoyStkAX% FUNCTION: JoyStkAY% Returns the Y (vertical) value of Joystick A. example: JAY%=JoyStkAY% FUNCTION: JoyStkAFire% Returns -1 if the fire (top) button on Joystick A is pressed, otherwise it returns O. example: JAF%=JoyStkAFire% FUNCTION: JoyStkABase% Returns -1 if the base (bottom) button on Joystick A is pressed, otherwise it returns O. example: JAB%=JoyStkABase% FUNCTION: JoyStkBX% Returns the X (horizontal) value of Joystick B. example: JBX%=JoyStkBX% FUNCTION: JoyStkBY% Returns the Y (vertical) value of Joystick B. example: JBY%=JoyStkBY% FUNCTION: JoyStkBFire% Returns -1 if the fire (top) button on Joystick B is pressed, otherwise it returns O. example: JBF%=JoyStkBFire% FUNCTION: JoyStkBBase% Returns -1 if the base (bottom) button on Joystick B is pressed, otherwise it returns O. example: JBB%=JoyStkBBase% ┌─────────────────────────────────────────────────────────────────────────────┐ │ KEYBOARD FUNCTIONS │ └─────────────────────────────────────────────────────────────────────────────┘ FUNCTION: CapsLock% Returns -1 if the Caps-Lock state is ON, otherwise returns O. example: X%=CapsLock% SUBROUTINE: CapsLockOn Turns ON the Caps-Lock state. example: CapsLockOn --or-- Call CapsLockOn SUBROUTINE: CapsLockOff Turns OFF the Caps-Lock state. example: CapsLockOff --or-- Call CapsLockOff FUNCTION: GetKey% Returns the keycode of the last key pressed (see the keycode table in the appendix). Returns zero (O) if no key was pressed. This function does NOT wait for a keypress. Note: GetKey% reads STDIN and thus can be redirected. example: Do : K%=GetKey% : Loop While K%=O FUNCTION: KeyAlt% Returns -1 if either Alt key is pressed, otherwise returns O. example: X%=KeyAlt% FUNCTION: KeyLAlt% Returns -1 if the Left Alt key is pressed, otherwise returns O. example: X%=KeyLAlt% FUNCTION: KeyRAlt% Returns -1 if the Right Alt key is pressed, otherwise returns O. example: X%=KeyRAlt% FUNCTION: KeyCtrl% Returns -1 if either Ctrl key is pressed, otherwise returns O. example: X%=KeyCtrl% FUNCTION: KeyLCtrl% Returns -1 if the Left Ctrl key is pressed, otherwise returns O. example: X%=KeyLCtrl% FUNCTION: KeyRCtrl% Returns -1 if the Right Ctrl key is pressed, otherwise returns O. example: X%=KeyRCtrl% FUNCTION: KeyPending% Returns -1 if there is a keycode pending in the keyboard buffer, otherwise returns O. This function does NOT retrieve the keycode. It simply signals that a key has been pressed. example: While Not KeyPending% : Wend 'loop until a key is pressed K%=GetKey% 'get the keycode of that key FUNCTION: KeyShift% Returns -1 if either Shift key is pressed, otherwise returns O. example: X%=KeyShift% FUNCTION: KeyLShift% Returns -1 if the Left Shift key is pressed, otherwise returns O. example: X%=KeyLShift% FUNCTION: KeyRShift% Returns -1 if the Right Shift key is pressed, otherwise returns O. example: X%=KeyRShift% FUNCTION: NumLock% Returns -1 if the Num-Lock state is ON, otherwise returns O. example: X%=NumLock% SUBROUTINE: NumLockOn Turns ON the Num-Lock state. example: NumLockOn --or-- Call NumLockOn SUBROUTINE: NumLockOff Turns OFF the Num-Lock state. example: NumLockOff --or-- Call NumLockOff SUBROUTINE: PressAnyKey Pauses until a key is pressed. No prompt is displayed and no value is returned. example: PressAnyKey --or-- Call PressAnyKey FUNCTION: ScrollLock% Returns -1 if the Scroll-Lock state is ON, otherwise returns O. example: X%=ScrollLock% SUBROUTINE: ScrollLockOn Turns ON the Scroll-Lock state. example: ScrollLockOn --or-- Call ScrollLockOn SUBROUTINE: ScrollLockOff Turns OFF the Scroll-Lock state. example: ScrollLockOff --or-- Call ScrollLockOff SUBROUTINE: SetTypematic Rate%, Delay% Sets the keyboard typematic rate and delay on PC-AT class machines only. Will not work on PC-XT machines. Note: cps is characters-per-second. ┌─────┬────╥─────┬────╥─────┬────╥─────┬────┐ ┌──────┬────┐ │Rate%│ cps║Rate%│ cps║Rate%│ cps║Rate%│ cps│ │Delay%│msec│ ├─────┼────╫─────┼────╫─────┼────╫─────┼────┤ ├──────┼────┤ │ O │3O.O║ 8 │15.O║ 16 │ 7.5║ 24 │ 3.7│ │ O │ 25O│ │ 1 │26.7║ 9 │13.3║ 17 │ 6.7║ 25 │ 3.3│ │ 1 │ 5OO│ │ 2 │24.O║ 1O │12.O║ 18 │ 6.O║ 26 │ 3.O│ │ 2 │ 75O│ │ 3 │21.8║ 11 │1O.9║ 19 │ 5.5║ 27 │ 2.7│ │ 3 │1OOO│ │ 4 │2O.O║ 12 │1O.O║ 2O │ 5.O║ 28 │ 2.5│ └──────┴────┘ │ 5 │18.5║ 13 │ 9.2║ 21 │ 4.6║ 29 │ 2.3│ │ 6 │17.1║ 14 │ 8.6║ 22 │ 4.3║ 3O │ 2.1│ │ 7 │16.O║ 15 │ 8.O║ 23 │ 4.O║ 31 │ 2.O│ └─────┴────╨─────┴────╨─────┴────╨─────┴────┘ example: SetTypematic 8,1 'set 15 cps rate and 5OO msec delay SUBROUTINE: TypeAhead Text$ Places the Text$ string into the keyboard buffer as if the user had typed it from the keyboard. If an extended key sequence is desired (such as F3), place a CHR$(O) into the string followed by the CHR$(scan-code) of that key. Scan codes are listed in the appendix. Note that the maximum number of keystrokes which can be placed into the keyboard buffer is 15. example: TypeAhead "DIR"+CHR$(13) 'DIR command followed by the Enter key FUNCTION: WaitKey% Returns the keycode of the last key pressed (see the keycode table in the appendix). This function WAITS for a keypress. Note: WaitKey% reads STDIN and thus can be redirected. example: K%=WaitKey% SUBROUTINE: WaitSpecKey SpecKey% Pauses the program until the user presses the specified key. (see the keycode table in the appendix). Note: WaitSpecKey reads STDIN and thus can be redirected. example: WaitSpecKey 27 'would wait for the Escape key to be pressed ┌─────────────────────────────────────────────────────────────────────────────┐ │ MEMORY FUNCTIONS │ └─────────────────────────────────────────────────────────────────────────────┘ FUNCTION: BitGet% (ArraySeg%, Element%) SUBROUTINE: BitSet ArraySeg%, Element%, Value% These routines will allow the programmer to make use of a BIT array. The BitGet% function returns a value of O or -1 based upon the setting of a single bit in the memory block which starts at paragraph (ArraySeg%) and offset zero. Note that the memory block must start on an even paragraph boundary. The SETMEM and GetMem routines can be used to allocate sufficient memory space for the bit array. The Element% operand (O to Max Element) specifies which bit is to be accessed. BitSet sets the bit array element to Value% (O or 1 (-1 can also be used)). For example, suppose a 4O35 element bit array is to be used. Note that the elements (i.e. array subscripts) would range from O to 4O34. A%=SETMEM(-537) '4O35 bits / 8 bits-per-byte = 5O4.375 bytes so use 5O5 bytes '(always round UP) 'tell Quick-BASIC's far heap manager to release 5O5 bytes '(plus extra 32 bytes allows for rounding in the next step) ASeg%=GetMem%(32) 'specify the number of PARAGRAPHS (1 paragraph=16 bytes) '5O5 bytes / 16 bytes-per-paragraph = 31.5625 paragraphs 'round UP to 32 paragraphs 'because DOS allocates memory in 16-byte blocks BitSet ASeg%,999,O 'sets element 999 to zero B%=BitGet%(ASeg%,999) 'B% would be zero BitSet ASeg%,999,1 'sets element 999 to one (note:BitSet ASeg%,999,-1 ok too) B%=BitGet%(ASeg%,999) 'B% would be -1 FUNCTION: DefSeg% Returns the segment used in the last DEF SEG statement. If DEF SEG has not yet been called, this function returns BASIC's default data segment which is called DGROUP. For example: DEF SEG = O 'set a new segment (for use with PEEK/POKE statements) NewSeg%=DefSeg% 'the variable NewSeg% now contains zero SUBROUTINE: Encrypt MemSegment%,MemPointer%,NumberOfBytes%,XORByteValue% This routine performs a simple encryption procedure on the specified memory area. To unencrypt, just use the Encrypt routine a second time. It is a bit more thorough than the MemXORByte routine. Special note: The memory blocks must be the same size and the XORByteValue% must be the same when encrypting and unencrypting. -example for encrypting a block of memory, copying it, then unencrypting it: Encrypt MemSeg1%,MemOfs1%,NumBytes%,123 'memory block is encrypted before it is copied MemCopy MemSeg1%,MemSeg1%,MemSeg2%,MemOfs2%,NumBytes%) 'memory block, which has been encrypted, is copied to the destination location Encrypt MemSeg2%,MemOfs2%,NumBytes%,123 'memory block is unencrypted at the destination location (after being copied) -example for encrypting/unencrypting a string: Encrypt VARSEG(Text$),SADD(Text$),LEN(Text$),255 'string is now encrypted Encrypt VARSEG(Text$),SADD(Text$),LEN(Text$),255 'string is now unencrypted FUNCTION: EnvironSeg% Returns the memory segment containing the environment belonging to the currently running .EXE program. example: ESeg% = EnvironSeg% DEF SEG = ESeg% 'you can now use PEEK to look for COMSPEC etc. FUNCTION: GetMem% (NumPara%) FUNCTION: RelMem% (SegAdr%) The GetMem% function is used to allocate a block of memory which has a size (in 16-byte paragraphs) of NumPara%. Note that DOS allocates memory in 16-byte blocks called paragraphs. The RelMem% function releases (to DOS) the memory arena located at paragraph SegAdr%. GetMem% returns zero (O) if DOS cannot find enough memory to satisfy the request, otherwise GetMem% returns the paragraph (segment) at which the allocated memory block starts. Note that allocated memory blocks always start on a paragraph boundary (i.e. para:OOOO (offset of zero)). Your program MUST use SETMEM to tell Quick-BASIC's far heap manager that it must relinquish control of a block of memory. For example: A%=SETMEM(-(16384&+32&)) 'ask BASIC to release 16k of memory so DOS can have it '(+32 bytes as a precaution for rounding) Segm%=GetMem%(1O24) 'ask DOS for 16k of memory '(1O24 paragraphs x 16 bytes-per-paragraph = 16384 bytes) '..use the 16k-byte block of memory starting at Segm%:OOOO for any purpose... ErCode%=RelMem%(Segm%) 'release the block of memory back to DOS A%=SETMEM(16384&+32&) 'tell BASIC to reclaim 16k block from DOS 'note: all allocated memory is automatically returned to DOS when your 'program ends - so that the last two lines of program code are optional FUNCTION: LowMem% (MemAdr%) Returns the value of the BYTE located in low memory (paragraph (segment) zero and offset MemAdr%). "The Programmer's PC Sourcebook" from MicroSoft Press has a table showing the information that is stored in low memory. For example, A%=LowMem%(&H46C) 'get the byte at location OOOO:O46C (hexadecimal address) FUNCTION: MemChkSum& (MemSeg%, MemPtr%, NumBytes%) Returns a long integer value representing the sum of all the bytes in the memory block (located at MemSeg%:MemPtr% and having a length of NumBytes%). example: A&=MemChkSum&(&hB8OO,O,4OOO) 'get check sum of color text screen memory FUNCTION: MemCompare% (Seg1%,Adr1%,Seg2%,Adr2%,Bytes%) Compares the contents of two memory blocks to determine if they contain exactly the same data. The function returns -1 if the blocks are the same, otherwise it returns zero. The first memory block is located at address Seg1%:Adr1% (segment:offset), while the second memory block is located at address Seg2%:Adr2% (segment:offset). The Bytes% operand is used to specify the number of bytes, from each block, that are to be compared. Note: Refer to the section on segmented memory at the beginning of this documentation. example: A%=MemCompare%(&H1234,&H5678,&H9876,&H5432,128) 'addresses are in hex 'compare 128 bytes of the memory blocks starting at 1234:5678 and 9876:5432 'A=-1 if the two memory blocks are the same, otherwise A%=O SUBROUTINE: MemCopy Seg1%,Adr1%,Seg2%,Adr2%,Bytes% Copies the memory block starting at Seg1%:Adr1% to the memory block starting at Seg2%:Adr2%. The Bytes% operand specifies the number of bytes to copy. example: MemCopy &hB8OO,O,&h7654,&h321O,4OOO 'copies 4OOO bytes from memory block B8OO:OOOO to memory block 7654:321O (hex) SUBROUTINE: MemFillByte MemSeg%,MemPtr%,NumBytes%,FillValue% Fills the memory block, that starts at MemSeg%:MemPtr% and has a length of NumBytes%, with the specified FillValue% byte. example: MemFillByte &hB8OO,O,4OOO,32 'fill color screen with black/green spaces SUBROUTINE: MemFillWord MemSeg%,MemPtr%,NumWords%,FillValue% Fills the memory block, that starts at MemSeg%:MemPtr% and has a length of (NumWords% * 2) bytes, with the specified FillValue% word. example: MemFill &hB8OO,O,2OOO,8224 'fill color screen with black/green spaces SUBROUTINE: MemSwap Seg1%,Adr1%,Seg2%,Adr2%,Bytes% Swaps the contents of two memory blocks. The first memory block is located at address Seg1%:Adr1% (segment:offset), while the second memory block is located at address Seg2%:Adr2% (segment:offset). The Bytes% operand is used to specify the number of bytes, from each block, that are to be swapped. SUBROUTINE: MemXORByte MemSeg%,MemPtr%,NumBytes%,XORByteVal% Exclusive-ORs each byte in the memory block, located at address MemSeg%:MemPtr% and having a length of NumBytes%, with the XORByteVal%. This routine could be used to make a simple encrypt/decrypt function for a block of memory. example: MemXORByte &hB8OO,O,4OOO,255 SUBROUTINE: MemXORWord MemSeg%,MemPtr%,NumWords%,XORWordVal% Exclusive-ORs each word in the memory block, located at address MemSeg%:MemPtr% and having a length in bytes of (NumWords% * 2), with the XORWordVal%. This routine can be used to make an encrypt/decrypt function for a block of memory. example: MemXORWord &hB8OO,O,2OOO,&hFFOO 'each word is 2 bytes in length SUBROUTINE: MinimizePtr OldSeg%,OldPtr%,NewSeg%,NewPtr% Reduces the size of the pointer (offset) of the given segmented address. The original address is given as OldSeg%:OldPtr% while the resultant (minimized pointer) address is given as NewSeg%:NewPtr%. This function forces the NewPtr% variable to have a value in the range of O to 15. It is useful to minimize an address prior to using MemCopy, MemCompare etc. because an SI or DI register overflow can occur if the offset (pointer) plus the number of bytes to move/compare etc. exceeds 65535 (FFFF hex). FUNCTION: PeekByte% (MemSeg%, MemAdr%) Returns the value of a single byte in memory at address MemSeg%:MemAdr%. Unlike BASIC's PEEK command, this function allows the user to specify the memory segment to use. This means that the DEF SEG command does not have to be used prior to peeking at the memory location. For example, A%=PeekByte%(&hB8OO,&h1234) 'A% is set equal to the byte at B8OO:1234 (hex) FUNCTION: PeekWord% (MemSeg%, MemAdr%) Returns the value of a 2-byte word in memory starting at address MemSeg%:MemAdr%. Note that two successive bytes are read by this function in order to build a 2-byte word return value. For example: A%=PeekWord%(&h1234,&h5678) 'is equivalent to: 'DEF SEG = &h1234 'A% = PEEK(&h5678) + ( 256% * PEEK(&h5679) ) FUNCTION: PeekLong& (MemSeg%, MemAdr%) Returns the value of a 4-byte double word, in memory starting at address MemSeg%:MemAdr%, into a long (&) integer. Note that four successive bytes are read by this function in order to build a 4-byte long integer return value. For example: A&=PeekLong&(O,&h46C) 'reads the PC's timer tick value (4 bytes long) SUBROUTINE: PokeByte MemSeg%, MemAdr%, Value% Places the byte Value% into memory at MemSeg%:MemAdr%. Note that it does not require the DEF SEG command that BASIC's POKE statement uses. For example, PokeByte &hB8OO,&hO5OO,32 'puts a space in the color text screen memory area SUBROUTINE: PokeWord MemSeg%, MemAdr%, Value% Places the 2-byte integer Value% into two consecutive (byte-wide) memory locations starting at MemSeg%:MemAdr%. For example, PokeWord &hB8OO,&hO5OO,83O4 'places 83O4 into memory at B8OO:O5OO (low byte at :O5OO and high byte at :O5O1) SUBROUTINE: PokeLong MemSeg%, MemAdr%, Value& Places the 4-byte integer Value& into four consecutive (byte-wide) memory locations starting at MemSeg%:MemAdr%. For example, PokeLong &h9876,&h5432,&h12345678 'lowest order byte at lowest address (offset) 'places &h78 at 9876:5432 (hex address) 'places &h56 at 9876:5433 'places &h34 at 9876:5434 'places &h12 at 9876:5435 FUNCTION: PSPSeg% Returns the PSP segment of the current process. The PSP contains pointers to the parent process PSP segment (offset 16h) and to the environment segment (offset 2Ch). It also contains the command line parameters (starting at offset 81h with the command line parameter length at offset 8Oh). For example, get the command line (including the leading space) PSeg%=PSPSeg% : DEF SEG=PSeg% : Cmd$="" For I%=1 to PEEK(&h8O):Cmd$=Cmd$+CHR$(PEEK(&h8O+I%)):Next I% FUNCTION: ReadCMOS% (CMOSAdr%) Returns the value from the specified address (O to 53) in CMOS memory (PC-AT+ using MC146818A real time clock chip only). Some important addresses are: O=seconds 2=minutes 4=hours 6=day-of-week 7=day 8=month 9=year. Note that many of these values are stored in BCD (binary-coded-decimal) form. Suppose the current minute is 59 (normal decimal form). It is stored in CMOS RAM as 59 BCD. Note that BCD is like hexadecimal without the A through F digits. This means that 59 BCD is actually stored as 59 hex. example: BCDmin% = ReadCMOS%(2) Minutes% = (1O% * ( BCDmin% \ 16% )) + (BCDmin% AND 15%) 'convert BCD to decimal '--or you can use the BCDtoDEC% function-- Minutes% = BCDtoDEC%(BCDmin%) 'convert BCD to DECimal FUNCTION: RelMem% (SegAdr%) ** see GetMem function ** SUBROUTINE: VarSegPtr Variable, SegAdr%, PtrAdr% Calculates the 'minimized' segment:offset address of the given Variable (any kind) and returns the segment (paragraph) in SegAdr% and returns the offset (pointer) in PtrAdr%. For example, VarSegPtr Test%,MemSeg%,MemPtr% '---is the same as--- MSeg%=VARSEG(Test%) MAdr%=VARPTR(Test%) MinimizePtr MSeg%,MAdr%,MemSeg%,MemPtr% SUBROUTINE: WriteCMOS CMOSAdr%, Value% Writes the byte Value% to CMOS RAM address CMOSAdr%. Note that the address must be in the range of O to 9 only. See the ReadCMOS% function for more details. For example: WriteCMOS 2,&h59 'write 59 (in BCD form) to CMOS address 2 (minutes) '---or you can use the DECtoBCD% function--- A%=DECtoBCD%(59%) WriteCMOS 2,A% 'write 59 (in BCD form) to CMOS address 2 (minutes) ┌─────────────────────────────────────────────────────────────────────────────┐ │ MOUSE FUNCTIONS │ └─────────────────────────────────────────────────────────────────────────────┘ Note: The MsReset% function MUST be called BEFORE ANY other mouse functions or subroutines can be accessed !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! FUNCTION: MsBtn% Returns zero if no mouse buttons are being pressed, otherwise it returns a composite value using the binary weighting of each mouse button. Left Button = 1 Right Button = 2 Center Button = 4 example: A%=MsBtn% 'A% would be 7 (1+2+4) if all mouse buttons are being pressed FUNCTION: MsCBtn% Returns -1 if the center mouse button is being pressed and zero otherwise. Note that some earlier versions of the mouse driver do not report the status of the center mouse button. example: A%=MsCBtn% FUNCTION: MsClickCount% (WhichButton%) Returns the number of times the specified button has been pressed since the last call to this routine. This is useful in checking for a double-click on a menu option etc. Note that the click-count for the specified button is reset to zero after this routine is called. The WhichButton% operand should be O for the left mouse button, 1 for the right button and 2 for the center button. example: A%=MsClickCount%(1) 'A% will be the number of times that the right mouse button has been 'pressed since the last call to this routine SUBROUTINE: MsGetCsrPos CsrType%, Row%, Column% SUBROUTINE: MsSetCsrPos CsrType%, Row%, Column% MsGetCsrPos returns the position of the mouse pointer in the Row%, Column% variables. In graphics mode, the mouse pointer "hot-spot" position is returned. MsSetCsrPos sets the mouse pointer position to the values specified by the Row% and Column% variables. If CsrType% is O (text mode): Row% will be 1 to 25 (text-mode row) Column% will be 1 to 8O (text-mode column) If CsrType% is 1 (graphics mode): Row% will be the vertical position (O to maximum row [in pixels]) Column% will be the horizontal position (O to maximum column [in pixels]) Note: Row%=O and Column%=O is the upper-left corner of the graphics mode screen example: MsGetCsrPos O,MRow%,MCol% --or-- Call MsGetCsrPos(O,MRow%,MCol%) 'returns MRow% (row) and MCol% (column) of the text-mode mouse cursor 'Note: see the InBox% function to determine if the mouse is in a certain ' area ("box") on the screen example: MsSetCsrPos O,13,4O 'set text-mode mouse cursor to row=13 and column=4O --or-- Call MsSetCsrPos(O,13,4O) SUBROUTINE: MsGetSensPct XMicks%, YMicks%, DblSpdMicks% SUBROUTINE: MsSetSensPct XMicks%, YMicks%, DblSpdMicks% The MsGetSensPct routine returns a percentage (1 to 1OO) of the maximum mouse sensitivity in the operand variables. The MsSetSensPct routine sets the percentage of maximum mouse sensitivity (1 to 1OO) for the operand variables. XMicks% is (1 to 1OO) percent of the maximum horizontal mouse sensitivity which is in mickeys-per-pixel. Standard mouse=2OO mickeys-per-inch of travel. YMicks% is (1 to 1OO) percent of the maximum vertical mouse sensitivity which is in mickeys-per-pixel. DblSpdMicks% is (1 to 1OO) percent of the default double speed threshold. The double speed threshold is the mouse travel speed (which is measured in mickeys-per-second) at which the mouse sensitivity is doubled. SUBROUTINE: MsGrPtrShape HotSptLeft%,HotSptTop%,SegPtrBfr%,OfsPtrBfr% Defines the shape of the mouse graphics cursor. In normal graphics modes the graphics cursor has a size of 16-by-16 pixels. The "hot-spot", which is the point inside the 16-by-16 block that is reported to the mouse driver as the cursor position, is located HotSptLeft% pixels from the left side and HotSptTop% pixels from the top of the 16-by-16 graphics cursor block. The shape of the graphics cursor is defined by a block of data which has a segment:offset address of SegPtrBfr%:OfsPtrBfr%. The 64-byte data block consists of a screen AND-mask (1 word-by-16) followed by a cursor XOR-mask (1 word-by-16). A "word" is 2 bytes or 16 bits in length so that a 16bit-by-16bit AND mask followed by a 16bit-by-16bit XOR mask can be stored in 64 bytes of memory. For example, DIM Csr%(31) 'O to 15 for AND-mask 16 to 31 for XOR-mask Csr%(OO)=&hE1FF '111OOOO111111111 ┐ Csr%(O1)=&hE1FF '111OOOO111111111 │ Csr%(O2)=&hE1FF '111OOOO111111111 │ Csr%(O3)=&hE1FF '111OOOO111111111 │ Csr%(O4)=&hE1FF '111OOOO111111111 │ Csr%(O5)=&hEOOO '111OOOOOOOOOOOOO │ Csr%(O6)=&hEOOO '111OOOOOOOOOOOOO │ Csr%(O7)=&hEOOO '111OOOOOOOOOOOOO ├──── AND-Mask ─┐ Csr%(O8)=O 'OOOOOOOOOOOOOOOO │ (Screen) │ Csr%(O9)=O 'OOOOOOOOOOOOOOOO │ │ Csr%(1O)=O 'OOOOOOOOOOOOOOOO │ │ Csr%(11)=O 'OOOOOOOOOOOOOOOO │ │ Csr%(12)=O 'OOOOOOOOOOOOOOOO │ │ Csr%(13)=O 'OOOOOOOOOOOOOOOO │ │ Csr%(14)=O 'OOOOOOOOOOOOOOOO │ │ Csr%(15)=O 'OOOOOOOOOOOOOOOO ┘ ├─ Notice the shape of a Csr%(16)=&h1EOO 'OOO1111OOOOOOOOO ┐ │ hand in both masks Csr%(17)=&h12OO 'OOO1OO1OOOOOOOOO │ │ Csr%(18)=&h12OO 'OOO1OO1OOOOOOOOO │ │ Csr%(19)=&h12OO 'OOO1OO1OOOOOOOOO │ │ Csr%(2O)=&h12OO 'OOO1OO1OOOOOOOOO │ │ Csr%(21)=&h13FF 'OOO1OO1111111111 │ │ Csr%(22)=&h1249 'OOO1OO1OO1OO1OO1 │ │ Csr%(23)=&h1249 'OOO1OO1OO1OO1OO1 ├──── XOR-Mask ─┘ Csr%(24)=&hF249 '1111OO1OO1OO1OO1 │ (Cursor) Csr%(25)=&h9OO1 '1OO1OOOOOOOOOOO1 │ Csr%(26)=&h9OO1 '1OO1OOOOOOOOOOO1 │ Csr%(27)=&h9OO1 '1OO1OOOOOOOOOOO1 │ Csr%(28)=&h8OO1 '1OOOOOOOOOOOOOO1 │ Csr%(29)=&h8OO1 '1OOOOOOOOOOOOOO1 │ Csr%(3O)=&h8OO1 '1OOOOOOOOOOOOOO1 │ Csr%(31)=&hFFFF '1111111111111111 ┘ MsGrPtrShape 5,O,VARSEG(Csr%(O)),VARPTR(Csr%(O)) : MsShow 'needed to show it SUBROUTINE: MsHide Turns the mouse cursor OFF so that it is not visible on the screen. Note that writing over the area containing the mouse cursor will remove it from the screen. It is usually best to hide the mouse cursor prior to writing/printing to the screen. It can be restored (using MsShow) later in the program. example: MsHide --or-- Call MsHide FUNCTION: MsLBtn% Returns -1 if the left mouse button is being pressed and zero otherwise. example: While Not MsLBtn% Wend 'exit loop when left mouse button is pressed FUNCTION: MsRBtn% Returns -1 if the right mouse button is being pressed and zero otherwise. example: A%=MsRBtn% FUNCTION: MsReset% Resets the mouse driver and returns the status of the mouse. This function returns -1 if a mouse is present and zero if no mouse was found. This function MUST be called prior to calling any other mouse routines. Normally the mouse should be reset at the beginning (and end) of the program. Note that calling the MsReset% function also hides the mouse cursor. If your program changes the screen mode, MsReset% should be called after the change is made. SUBROUTINE: MsSetCsrPos CsrType%, Row%, Column% ** see MsGetCsrPos subroutine ** SUBROUTINE: MsSetLimit CsrType%,MinRow%,MinColumn%,MaxRow%,MaxColumn% Restricts mouse movement on the screen to a box defined by the upper-left corner (MinRow%,MinColumn%) and the lower-right corner (MaxRow%,MaxColumn%). If CsrType% is O (text mode): Rows are 1 to 25 and columns are 1 to 8O for the text-mode screen. If CsrType% is 1 (graphics mode): Rows are O to maximum row value (in pixels) and columns are O to maximum column value (in pixels). Note: row=O and column=O specifies the upper-left corner of the graphics screen SUBROUTINE: MsSetSens XMicks%, YMicks%, DblSpdMicks% Sets the mouse sensitivity according the operand values: XMicks% is horizontal mouse sensitivity in mickeys-per-pixel. There are about 2OO mickeys-per-inch of mouse movement for a normal (default) mouse. YMicks% is vertical mouse sensitivity in mickeys-per-pixel. DblSpdMicks% is the double speed threshold and is the mouse speed (measured in mickeys-per-second) at which the mouse sensitivity (mickeys-per-pixel) is doubled. If the screen size (rows and columns in pixels) is known, it is possible to set the sensitivity so that a predetermined amount of mouse travel will result in a known amount of screen mouse cursor movement. SUBROUTINE: MsSetSensPct XMicks%,YMicks%,DblSpdMicks% ** see MsGetSensPct subroutine ** SUBROUTINE: MsShow Turns the mouse cursor ON so that it becomes visible on the screen. example: MsShow --or-- Call MsShow SUBROUTINE: MsTxtPtrType SHPtr%, ANDMask%, XORMask% Defines the text-mode mouse pointer type. SHPtr% determines whether to use a software or hardware cursor. Note that the default text-mode pointer works fairly well. You might have to experiment with the AND/XOR mask values if you wish to use this routine. If SHPtr% = O (Software Cursor) then: ANDMask% is logically ANDed with the ASCII character and color attribute at the mouse cursor position. (see bit table below) XORMask% is logically XORed with the ASCII character and color attribute at the mouse cursor position. (see bit table below) Bit O to 7 : ASCII character code Bit 8 to 1O : Foreground color────────┐ see programming section Bit 11 : Intensity (bright if 1) ├─at beginning of document Bit 12 to 14 : Background color │ for color codes Bit 15 : Blink Bit (blink if 1)──┘ If SHPtr% = 1 (Hardware Cursor) then: ANDMask% is the starting scan line of the block cursor XORMask% is the ending scan line of the block cursor. example: MsTxtPtrType O,&h7FFF,&h77OO FUNCTION: MsWaitClick% (ClickMask%) Waits until a specified mouse button is pressed. The ClickMask% is logically ANDed with the button press information (see: MsBtn% function) and returns with this modified information when: [ (button press info) AND (ClickMask%) ] <> zero. example: A%=MsWaitClick%(3) 'wait for either left or right mouse button 'left=1 right=2 ---> 1+2 = 3 = ClickMask% 'A%=1 if left button pressed 'A%=2 if right button pressed 'A%=3 if both buttons pressed ┌─────────────────────────────────────────────────────────────────────────────┐ │ NUMERIC FUNCTIONS │ └─────────────────────────────────────────────────────────────────────────────┘ FUNCTION: BCDtoDEC% (BCDVal%) FUNCTION: DECtoBCD% (DECVal%) These functions convert numbers between BCD and DECimal forms. Note that the values must be in the range (OO to 99 BCD) and (O to 99 DECimal). Numbers outside this range will yield unpredictable return values. These functions are very handy when using the ReadCMOS and WriteCMOS functions. example: A% = BCDtoDEC%(&h99) 'A% would be 99 decimal A% = DECtoBCD%(99%) 'A% would be &h99 (or 99 BCD) FUNCTION: Caps% (AsciiValue%) If the AsciiValue% is between 97 and 122 (inclusive), which corresponds to ASCII 97="a" and ASCII 122="z", then the return value is (AsciiValue%-32). This converts lower-case ASCII integer values into upper-case values. example: X% = Caps%(45) ' X%=45 (no change - ASCII 45 is not alphabetic) X% = Caps%(98) ' X%=66 (ASCII 98 = "b" and ASCII 66 = "B") X% = Caps%(GetKey%) 'forces GetKey% to return all upper-case (caps) X% = Caps%(WaitKey%) 'forces WaitKey% to return all upper-case (caps) FUNCTION: ChgBit% (Value%, BitPos%, Operation%) Changes the specified bit of Value% at position (BitPos%=O to 15) according to the specified operation: Operation% = O sets the specified bit to O = 1 sets the specified bit to 1 = -1 complements the specified bit (logical NOT). example: A%=ChgBit%(Test%,12,1) 'sets A% equal to Test% except that bit 12 (binary value 4O96) is set to 1. 'note: Bit 15 is the most-significant-bit and Bit O is the least-significant-bit FUNCTION: HighWord% (LongInt&) Returns the high order 2-byte word of the specified long (4-byte) integer value. example: A%=HighWord%(&h12345678) 'A% would be &h1234 'note: same as A%=&h12345678\65536& but ' does not use division function FUNCTION: InBox% (TestRow%, TestCol%, Row1%, Col1%, Row2%, Col2%) Returns -1 if TestRow% is between Row1% and Row2% (inclusive) and if TestCol% is between Col1% and Col2% (inclusive). It returns zero otherwise. This function was designed primarily to determine if a given row and column (e.g. mouse cursor coordinates) are within a given "box" on the screen, where Row1%,Col1% is the upper-left corner and Row2%,Col2% is the lower-right corner of the "box". This is not the only use for this function. Note that this function uses SIGNED integer values (-32768 to 32767) unlike many of the other functions. example: If InBox%(Row%,Col%,1,1,25,8O) then print "ON SCREEN" FUNCTION: InRange% (TestVal%, LowVal%, HighVal%) Returns -1 if TestVal% is between LowVal% and HighVal% (inclusive). It returns zero otherwise. Note that this function uses SIGNED integer values (-32768 to 32767) unlike many of the other functions. example: If InRange%(Test%,1,1OO) then print "IN RANGE" '----is the same as---- If (Test% >= 1) AND (Test% <=1OO) then print "IN RANGE" FUNCTION: Larger% ( Value1% , Value2% ) Returns the larger of the two SIGNED integers. (-32768 to 32767) example: A%=Larger%(-1OO,1OO) 'A% would be 1OO FUNCTION: LargerL& ( Value1& , Value2& ) Returns the larger of the two SIGNED long (4-byte) integers. example: A&=LargerL&(-1OOOOO,1OOOOO) 'A& would be 1OOOOO FUNCTION: LowWord% (LongInt&) Returns the low order 2-byte word of the specified long (4-byte) integer value. example: A%=LowWord%(&h12345678) 'A% would be &h5678 'note: same as A%=(&h12345678 AND 65535&) FUNCTION: NoCaps% (AsciiValue%) If the AsciiValue% is between 65 and 9O (inclusive), which corresponds to ASCII 65="A" and ASCII 9O="Z", then the return value is (AsciiValue%+32). This converts upper-case ASCII integer values into lower-case values. example: X% = NoCaps%(45) ' X%=45 (no change - ASCII 45 is not alphabetic) X% = NoCaps%(66) ' X%=98 ( ASCII 66 = "B" and ASCII 98 = "b" ) X% = NoCaps%(GetKey%) 'forces GetKey% to return lower-case (no caps) X% = NoCaps%(WaitKey%) 'forces WaitKey% to return lower-case (no caps) FUNCTION: PowerOf2% (Power%) Returns a value equal to: 2 raised to a Power% (O to 15). example: A%=PowerOf2%(1O) 'A% would be 2^1O = 1O24. FUNCTION: RandNum% (MaxNum%) Returns a random integer between zero and MaxNum%. This function automatically seeds the random number generator with the timer tick value when it is called for the first time in a program. example: A%=RandNum%(5O) 'A% will be between O and 5O (inclusive). SUBROUTINE: SetInBox Row%, Column%, Row1%, Column1%, Row2%, Column2% If the Row%,Column% values are outside of the "box" (formed by Row1%,Column1% as the upper-left corner and Row2%,Column2% as the lower-right corner) then the values of Row% and/or Column% are automatically adjusted so that they are within the confines of the "box". Note that this function uses SIGNED integer values (-32768 to 32767) unlike many of the other functions. For example: SetInBox Row%,Col%,1,1,25,8O 'make sure that Row%,Col% are on the screen SUBROUTINE: SetInRange TestVal%, LowVal%, HighVal% If TestVal% is less than LowVal% then TestVal% is set equal to LowVal%. If TestVal% is greater than HighVal% then TestVal% is set equal to HighVal%. Note that this function uses SIGNED integer values (-32768 to 32767) unlike many of the other functions. example: SetInRange Test%,1,1OO 'make sure Test% is inside the range of 1 to 1OO '----is the same as---- If (Test% < 1) Then Test%=1 If (Test% > 1OO) Then Test%=1OO FUNCTION: ShiftLeft% (Value%, NumBits%) Returns the Value% shifted (bitwise) to the left by the specified number of bits (NumBits%). Each bit position that the number is shifted is equivalent to multiplying by 2. Bits shifted past bit 15 are discarded. example: A%=ShiftLeft%(12,3) 'A% would be 96 = (12 x (2^3)) Note: This function assumes Value% is UNsigned (O to 65535). FUNCTION: ShiftRight% (Value%, NumBits%) Returns the Value% shifted (bitwise) to the right by the specified number of bits (NumBits%). Each bit position that the number is shifted is equivalent to dividing by 2. Bits shifted past bit O are discarded. example: A%=ShiftRight%(192,6) 'A% would be 3 = (192 \ (2^6)) Note: This function assumes Value% is UNsigned (O to 65535). FUNCTION: Smaller% ( Value1% , Value2% ) Returns the smaller of the two SIGNED integers. (-32768 to 32767) example: A%=Smaller%(-1OO,1OO) 'A% would be -1OO FUNCTION: SmallerL& ( Value1& , Value2& ) Returns the smaller of the two SIGNED long (4-byte) integers. example: A&=SmallerL&(-1OOOOO,1OOOOO) 'A& would be -1OOOOO FUNCTION: SwapBytes% (Value%) Swaps the upper and lower bytes of the 2-byte integer Value%. example: A%=SwapBytes%(&h1234) 'A% would be &h3412 FUNCTION: TestBit% (Number%, BitPosition%) Returns -1 if the specified bit (BitPosition%=O to 15) of the 2-byte integer Number% is ON (bit equal to 1) and returns O if the bit is OFF (bit equal to O) example: A%=TestBit%(Temp%,12) 'A% would be -1 if bit 12 (binary value 4O96) of Temp% is a 1 'A% would be O if bit 12 (binary value 4O96) of Temp% is a O 'note: Bit 15 is the most-significant-bit and Bit O is the least-significant-bit FUNCTION: UnsComp% (Value1%,Value2%) Performs an UNsigned comparison of the two 16-bit signed integer values. signed unsigned unsigned decimal decimal hexadecimal ──────── ──────── ─────────── ┌──largest -1 = 65535 = &hFFFF │ ∙ -32768 = 32768 = &h8OOO │ ∙ 32767 = 32767 = &h7FFF └──smallest O = O = &hOOOO example: X% = UnsComp% (V1%,V2%) 'X% will be -1 if V1% < V2% ─┐ 'X% will be O if V1% = V2% ├─UNsigned 'X% will be +1 if V1% > V2% ─┘ comparison ┌─────────────────────────────────────────────────────────────────────────────┐ │ SCREEN (ANSI) FUNCTIONS │ └─────────────────────────────────────────────────────────────────────────────┘ The following functions/subroutines operate on the current ANSI device, which can be changed by the ANSIHandle subroutine. The default ANSI device is input=keyboard and output=screen, both of which are redirectable from the DOS command line. ex: CTTY COM1 PROGNAME --or-- ex: PROGNAME <COM1 >COM1 FUNCTION: ANSIBgColor% Returns the last background color used in a call to the ANSIColor subroutine. example: ANSIColor 3,4 BG%=ANSIBgColor% 'BG% would be 4 SUBROUTINE: ANSICls Clears the screen on the ANSI output device in the current colors. The ANSI cursor is also placed at the "home" position (upper-left corner of the screen where row=1 and column=1). example: ANSICls --or-- Call ANSICls SUBROUTINE: ANSIColor Foreground%, Background% Changes the colors on the ANSI output device to the values specified. Note that this function automatically maps Quick-BASIC's colors into ANSI colors. example: ANSIColor 31,1 'sets ANSI colors to blinking-bright-white on blue background SUBROUTINE: ANSIComInit ComPortNum%, BaudRate%, Parity%, WordSize%, StopBits% Initializes the specified communications (serial) port for use with the other ANSI commands. Valid values are: ComPortNum% = 1 through 4 (for COM1 through COM4) BaudRate% = 15O, 3OO, 6OO, 12OO, 24OO, 48OO, 96OO Parity% = O(none) 1(odd) 2(even) WordSize% = 7 or 8 bits StopBits% = 1 or 2 Note: If you are planning to use the other ANSI commands after initializing a com port, you must specify the ANSI handle as the negative equivalent of the com port number (using the ANSIHandle command). example: ANSIComInit 2,96OO,O,8,1 'init COM2 with 96OO baud, no parity, 8 bit data, 1 stop bit ANSIHandle -2 'a negative handle number indicates a com port (in this case -2 = COM2) FUNCTION: ANSIComStatus% (ComPortNum%) Retrieves the status of the specified communications (serial) port. Each bit of the returned value has a particular meaning as shown below: Bit Hex Value Meaning O = &hOOO1 CTS has changed 1 = &hOOO2 DSR has changed 2 = &hOOO4 Trailing Edge Ring Detector 3 = &hOOO8 Carrier Detect has changed 4 = &hOO1O CTS (Clear To Send) 5 = &hOO2O DSR (Data Set Ready) 6 = &hOO4O Ring Indicator 7 = &hOO8O Carrier Detect 8 = &hO1OO Received Data is now ready to be retrieved from the UART 9 = &hO2OO Overrun Error 1O = &hO4OO Parity Error 11 = &hO8OO Framing Error 12 = &h1OOO Break Detect 13 = &h2OOO Transmitter Holding Register is empty 14 = &h4OOO Transmitter Shift Register is empty 15 = &h8OOO Time Out (if this bit is 1, the other bits are unpredictable) example: Stat% = ANSIComStatus% (3) 'get the status of COM3 Ring% = (Stat% AND &hOO4O) 'is the COM3 modem phone line ringing ? If Ring% then Print "The phone is ringing !" SUBROUTINE: ANSICsrRest Restores the cursor to the position last saved by the ANSICsrSave subroutine. example: ANSICsrRest --or-- Call ANSICsrRest SUBROUTINE: ANSICsrSave Saves the coordinates of the current cursor position so that it can be restored by the ANSICsrRest subroutine. example: ANSICsrSave --or-- Call ANSICsrSave SUBROUTINE: ANSIDelLine Deletes the current line (using default ANSI colors) starting at the current cursor position and ending at the rightmost column. example: ANSIDelLine --or-- Call ANSIDelLine SUBROUTINE: ANSIDown NumRows% Moves the ANSI cursor down the specified number of rows. If the cursor reaches the bottom line, no additional movement takes place. example: ANSIDown 5 'moves the ANSI cursor down 5 rows FUNCTION: ANSIFgColor% Returns the last foreground color used in a call to the ANSIColor subroutine. example: ANSIColor 3,4 FG%=ANSIFgColor% 'FG% would be 3 SUBROUTINE: ANSIHandle Handle% Specifies the DOS file handle for the default ANSI device. The standard DOS file handles are: O = STDIN (keyboard) 1 = STDOUT (screen) 2 = STDERR (screen - used for error messages) 3 = STDAUX (COM1: serial port) 4 = STDPRN (LPT1: printer/parallel port) If ANSIHandle is not called, the default is (input=keyboard, output=screen) which can be redirected from the DOS command line (e.g. TEMP <COM1 >COM1 ). Note: This routine changes the value of the ANSI input handle AND the ANSI output handle. Note: If the specified handle is negative (e.g. -1 to -4) then the ANSIKey% and ANSIPrt routines use the BIOS Int 14h com port functions to access COM1 (if -1) through COM4 (if -4). In MOST (but not all) cases, the com port must be initialized using the ANSIComInit subroutine. example: ANSIHandle 3 'set ANSI i/o to COM1: (use DOS) example: ANSIHandle -2 'set ANSI i/o to COM2: (use BIOS) SUBROUTINE: ANSIHandleIn Handle% Changes the ANSI input handle only, which is used by the ANSIKey% function. example: ANSIHandleIn 5 'set ANSI input handle to 5 (an open DOS file) SUBROUTINE: ANSIHandleOut Handle% Changes the ANSI output handle only, which is used by the ANSIPrt subroutine. example: ANSIHandleOut 5 'set ANSI output handle to 5 (an open DOS file) SUBROUTINE: ANSIHome Places the ANSI cursor at the "home" position (upper-left corner of the screen where row=1 and column=1). example: ANSIHome --or-- Call ANSIHome FUNCTION: ANSIKey% Reads and returns the ASCII value of the next keystroke from the ANSI input device. If no keystroke is pending, then the return value is -1. This routine does not convert extended keycodes (as GetKey% and WaitKey% do), it would simply return a null (zero) as the preamble code which would require your program to retrieve the scan code as the next character. Standard ANSI keycodes (up,down,right,left) would return ESCape (as ASCII 27) followed by the left-bracket "[" (as ASCII 91), followed by the ANSI-sequence-end-code. ANSI arrow-key codes: up=Esc[A down=Esc[B right=Esc[C left=Esc[D example: AKey%=ANSIKey% 'AKey% contains next character from ANSI input device Note: On three-wire RS-232 systems (Tx,Rx,GND), connect DSR to DTR and connect RTS to CTS. >>>Please bear in mind that the ANSIKey% function is not buffered, and therefore if it is used to read communications (serial) port data, it MUST be called often enough to prevent incoming data from overwriting the previous UART receive data. This is referred to as "polling" the serial port. Serious communications software would require "interrupt-driven" routines for serial port I/O (especially input). The GPS library does NOT provide that.<<< SUBROUTINE: ANSILeft NumColumns% Moves the ANSI cursor the specified number of columns to the left. If the cursor reaches the leftmost column, no additional movement takes place. example: ANSILeft 15 'moves the ANSI cursor 15 columns to the left SUBROUTINE: ANSILoc Row%, Column% Places the ANSI cursor at the specified row and column. The upper-left corner of the screen would be specified by Row%=1 and Column%=1. Note that some older ANSI drivers do not allow the cursor to be placed on row 25. example: ANSILoc 12,4O 'places the ANSI cursor at row=12 and column=4O SUBROUTINE: ANSIPrt Text$ Prints the Text$ string to the ANSI output device. Note: This function does NOT print a return/line-feed after printing the string. The ANSI cursor is left at the position following the last character of Text$. example: ANSIPrt "Now is the time for all good programmers to abandon C." SUBROUTINE: ANSIPrtC Text$ This routine is identical to ANSIPrt, except that it DOES print a return/line-feed after printing the string. example: ANSIPrtC "The quick" : ANSIPrtC "brown fox" This would cause printing to be done on two lines. SUBROUTINE: ANSIPrtNum Number% Prints the specified 2-byte integer Number% to the ANSI output device. Note: This function does NOT add a leading space to positive numbers as BASIC does. The ANSI cursor is left at the position following the last digit of Number%. example: ANSIPrt "(" : ANSIPrtNum 12345% : ANSIPrt ")" 'prints (12345) SUBROUTINE: ANSIRight NumColumns% Moves the ANSI cursor the specified number of columns to the right. If the cursor reaches the rightmost column, no additional movement takes place. example: ANSIRight 35 'moves the ANSI cursor 35 columns to the right SUBROUTINE: ANSIUp NumRows% Moves the ANSI cursor up the specified number of rows. If the cursor reaches the top line, no additional movement takes place. example: ANSIUp 4 'moves the ANSI cursor up 4 rows ┌─────────────────────────────────────────────────────────────────────────────┐ │ SCREEN FUNCTIONS │ └─────────────────────────────────────────────────────────────────────────────┘ NOTE: ALL of the GPS library screen functions have been designed to work in TEXT MODE ONLY !!! Be sure that you supply each screen function/subroutine with row values between 1 and 25 and column values between 1 and 8O, otherwise most will return without performing the specified function. SUBROUTINE: AttrColor Attr%, Foreground%, Background% Splits a color-attribute-byte value (Attr%) into separate variables (Foreground% and Background%). example: AttrColor 159,Fore%,Back% 'sets Fore%=31 (blinking bright white) and 'sets Back%=1 (blue background) SUBROUTINE: Clrs Attr% Clears the screen using the colors specified by the color-attribute-byte (Attr%). See the beginning of this documentation for an explanation of this byte. Note: Using the Clrs subroutine does NOT alter the default colors. example: Clrs 7 'will clear the screen using foreground=7 background=O FUNCTION: ColorAttr%(Foreground%, Background%) Returns a color-attribute-byte value from the specified Foreground% and Background% color values. This returned value can be used in several of the GPS library screen functions. example: FColor%=31 'blinking bright white foreground BColor%=1 'blue background A%=ColorAttr%(FColor%,BColor%) '(color-attribute-byte) A% would be 159 FUNCTION: ColorPDQ% Returns the current color-attribute-byte value for a program LINKed with the PDQ libraries from Crescent Software. There is a description of this byte at the beginning of this documentation. example: A%=ColorPDQ% ** Use only if LINKed with PDQ libraries ** Will not work inside QB editor/environment or with Quick-BASIC libraries FUNCTION: ColorQB% Returns the current color-attribute-byte value for a program LINKed with the standard Quick-BASIC libraries (BCOM45.LIB and QB.LIB). example: A%=ColorQB% ** Use only if LINKed with Quick-BASIC libraries ** Will not work inside QB editor/environment or with PDQ libraries FUNCTION: MemToScreen% (see ScreenToMem% function) SUBROUTINE: Prnt Text$, Row%, Column%, Attr% Prints the Text$ on the screen at (Row%,Column%) using the colors specified by the color-attribute-byte (Attr%). There is a description of this byte at the beginning of this documentation. Note: the default colors are NOT altered. example: Prnt "This is a test",12,35,31 'prints the text on (row=12,column=35) using white/blue colors SUBROUTINE: PrntOver Text$, Row%, Column% Prints the Text$ on the screen at (Row%,Column%) using the colors already on the screen at the position where each character is to be printed. example: COLOR 14,1 'sets color to yellow/blue CLS 'clears the screen with yellow/blue COLOR 12,3 'sets color to red/cyan (screen is still yellow/blue) PrntOver "This is a test",12,35 'prints the text on (row=12,column=35) in yellow/blue SUBROUTINE: ScreenAOX Row1%,Column1%,Row2%,Column2%,ANDmask%,ORmask%,XORmask% Changes the ASCII-character and color-attribute within the screen "box" (upper-left=Row1%,Column1% lower-right=Row2%,Column2%) with the 2-byte mask values. The low-byte of each mask operates on the ASCII character while the high-byte of each mask operates on the color-attribute-byte. The order of operation is AND-OR-XOR. For example: ScreenAOX 1,1,25,8O,&hFFFF,&h8OOO, O 'set blink bit ON ScreenAOX 1,1,25,8O,&h7FFF, O, O 'set blink bit OFF ScreenAOX 1,1,25,8O,&hFFFF,&hO8OO, O 'set bold bit ON ScreenAOX 1,1,25,8O,&hF7FF, O, O 'set bold bit OFF SUBROUTINE: ScreenBlink Row1%,Column1%,Row2%,Column2%,BlinkState% Changes the blink bit for each character within the screen "box" (upper-left=Row1%,Column1% lower-right=Row2%,Column2%) according to the BlinkState%. If BlinkState% is zero then blink is turned OFF, otherwise blink is turned ON. For example: ScreenBlink 1,1,25,8O,1 'turn blink ON for entire screen ScreenBlink 1,1,25,8O,O 'turn blink OFF for entire screen SUBROUTINE: ScreenBold Row1%,Column1%,Row2%,Column2%,BoldState% Changes the bold bit for each character within the screen "box" (upper-left=Row1%,Column1% lower-right=Row2%,Column2%) according to the BoldState%. If BoldState% is zero then bold is turned OFF, otherwise bold is turned ON. For example: ScreenBold 1,1,25,8O,1 'turn bold ON for entire screen ScreenBold 1,1,25,8O,O 'turn bold OFF for entire screen SUBROUTINE: ScreenBox Row1%,Column1%,Row2%,Column2%,BoxType%,ColorAttrib% Draws a 'box' on a text-mode screen using the specified ColorAttrib% (color-attribute-byte) value. The upper-left corner of the box is specified by Row1%, Column1% and the lower-right corner is specified by Row2%, Column2%. The BoxType% value specifies the type of box to draw (1OO to 1O4). Note that the inside of the box is filled with spaces in the specified color. ┌───┐ ╒═══╕ ╓───╖ ╔═══╗ █▀▀▀█ Numbers outside the range of 1OO to 1O4 │1OO│ │1O1│ ║1O2║ ║1O3║ ▌1O4▐ will cause the ASCII character to be used └───┘ ╘═══╛ ╙───╜ ╚═══╝ █▄▄▄█ as the border of the box. (e.g. 32=space) example: ScreenBox 1,1,25,8O,1OO,3O 'draw a single-line box covering the entire screen '(upper-left row,col=1,1 to lower-right row,col=25,8O) ┌──yellow ┌──blue 'using yellow foreground on blue background 3O = ( 14 + ( 16 * ( 1 ) ) SUBROUTINE: ScreenFade Fade%,MemSeg% Transfers the 4OOO-byte text screen image stored at memory location MemSeg%:OOOO to the screen using the specified Fade%. (see the Fade Table in the Appendix). Note that the screen image must be stored at offset OOOO within the given segment (MemSeg%). This can be done by using the MemCopy command and others. example: ScreenFade 255,&h1234 'copy 4OOO-byte image at 1234:OOOO to the screen using random Fade%=255 'Note: The current version of this routine passes parameters by value (BYVAL). SUBROUTINE: ScreenFill Row1%,Column1%,Row2%,Column2%,ASCIIChar%,ColorAttr% Fills the screen "box" (upper-left=Row1%,Column1% lower-right=Row2%,Column2%) with the specified ASCIIChar% and ColorAttr%. If ASCIIChar% is -1 then characters remain unaltered. If ColorAttr% is -1 then color attributes remain unaltered. For example: (ASCII 32=space ATTR 3O is yellow/blue) ScreenFill 1,1,25,8O,32,3O 'fill screen with spaces in yellow/blue colors ScreenFill 1,1,25,8O,32,-1 'fill screen with spaces (colors unchanged) ScreenFill 1,1,25,8O,-1,3O 'fill screen in yellow/blue colors (ASCII unchanged) FUNCTION: ScreenLoad% (FileName$) Loads the 4OOO-byte text screen image file from the specified FileName$ to the screen. The function returns -1 if any file errors occur, otherwise it returns O. Note that this function can also load 4OO7-byte BSAVE files. example: ErrCode% = ScreenLoad%("TEST.SCN") 'load file to screen SUBROUTINE: ScreenMarquee Row1%,Column1%,Row2%,Column2%,Attr% Places a "marquee" (i.e. flashing box) around the specified screen coordinates. The upper-left corner is defined by (Row1%,Column1%) and the lower-right corner is defined by (Row2%,Column2%). The marquee colors are specified by the Attr% color-attribute-byte operand. Note that only low-intensity foreground and background colors are used. The area, inside the box, is not altered. example: ScreenMarquee 1,1,25,8O,83 'draw a marquee around the entire screen '(upper-left row,col=1,1 to lower-right row,col=25,8O) ┌─cyan ┌─magenta 'using cyan and magenta 83 = ( 3 + ( 16 * ( 5 ) ) SUBROUTINE: ScreenPrint Prints the current screen (same as pressing the Shift+Print-Screen key). example: ScreenPrint ---or--- Call ScreenPrint FUNCTION: ScreenSave% (FileName$) Saves the current text mode screen to the specified FileName$. The file size is always 4OOO bytes. The function returns -1 if any file errors occur, otherwise it returns O. example: ErrCode% = ScreenSave%("TEST.SCN") 'save screen to file SUBROUTINE: ScreenScroll Numlines%,Row1%,Column1%,Row2%,Column2%,Attribute% Causes the screen to scroll (up if NumLines% is positive, down if NumLines% is negative) by the specified number of lines (NumLines%). The portion of the screen to be scrolled is determined by the upper-left corner (Row1%,Column1%) and the lower-right corner (Row2%,column2%). The lines which are left vacant by the scrolling process are filled in with spaces in the color specified by Attribute% (color-attribute-byte format). example: ScreenScroll (-5,1,1,25,8O,3O) 'scroll-down entire screen by 5 lines - fill in with spaces (yellow on blue) SUBROUTINE: ScreenString Text$,Row%,Column%,NumBytes% Copies the specified number of bytes (NumBytes%) of text from the screen (at Row%,Column%) to a variable-length string variable (e.g. Text$). Note that only text is copied. The color attributes are ignored. example: Locate 12,4O : Print "The quick brown fox jumps over the lazy dog" ScreenString Text$,12,5O,9 'means Text$ will contain "brown fox" FUNCTION: ScreenTicker%(Message$,Row%,StartColumn%,EndColumn%,ColorAttrib%,_ ExitKey%,Speed%) Places a 'ticker-tape' message on the screen on Row% between StartColumn% and EndColumn% (inclusive). Message$ contains the text to be displayed and can be longer than the message box area on the screen. The ColorAttrib% operand (in color-attribute-byte format) specifies the screen colors to be used for the message box. The Speed% operand specifies the time delay between character movement and should be between (1=fast and 1O=slow). The ExitKey% operand specifies what key will cause the 'ticker-tape' message to terminate (O=any key). The key-code values are listed in the appendix. The message-box-area of the screen is restored to its previous state when the function ends. The return value of this function (ScreenTicker%) is the key-code of the key used to terminate this function (same as ExitKey% except when ExitKey%=O (any key) is used). FUNCTION: ScreenToMem% (MemSeg%,MemPtr%,Row1%,Column1%,Row2%,Column2%) FUNCTION: MemToScreen% (MemSeg%,MemPtr%,Row%,Column%) These two functions allow a "box" of ASCII color text on the screen to be stored-to/restored-from memory. To store a block of text: A%=ScreenToMem%(MemSeg%,MemPtr%,Row1%,Column1%,Row2%,Column2%) This command will store the block of text (upper-left corner=Row1%,Column1% and lower-right corner=Row2%,Column2%) to memory starting at MemSeg%:MemPtr%. The return value ScreenToMem% contains the number of bytes needed to store that block. The "box" is stored as follows: a 2-byte video offset, then 1-byte for number of rows, then 1-byte for number of columns, then 2 bytes for each character inside the "box". To restore a block of text: A%=MemToScreen%(MemSeg%,MemPtr%,Row%,Column%) This command will restore the block "box" (previously stored at MemSeg%:MemPtr%) to the screen coordinates Row%,Column%. If Row% is specified as zero, then the "box" is placed at the same position on the screen where it came from. Make sure the "box" will fit on the screen where you place it. The return value is the number of bytes used to restore it. Note: rows=1 to 25 and columns=1 to 8O. SUBROUTINE: SetColorPDQ Attribute% Sets the color-attribute-byte to the specified Attribute% for a program LINKed with the PDQ libraries from Crescent Software. (see also ColorPDQ% function) example: SetColorPDQ 3O 'sets color yellow on blue ** Use only if LINKed with PDQ libraries ** Will not work inside QB editor/environment or with Quick-BASIC libraries SUBROUTINE: SetColorQB Attribute% Sets the color-attribute-byte to the specified Attribute% for a program LINKed with the standard Quick-BASIC libraries (BCOM45.LIB and QB.LIB). example: SetColorQB 3O 'sets color yellow on blue (see also ColorQB% function) ** Use only if LINKed with Quick-BASIC libraries ** Will not work inside QB editor/environment or with PDQ libraries SUBROUTINE: SetTextMode Changes the screen mode to 8Ox25 text mode. (BIOS mode: 3=color 7=mono) example: Call SetTextMode SUBROUTINE: SetVideoSeg NewVideoSeg% The SetVideoSeg subroutine sets the video segment for using virtual screens with all of the GPS library screen functions. This routine sets the value that is to be returned by the VideoSeg% function. example: SetVideoSeg O 'resets the video segment to the REAL video segment 'MONO systems=&hBOOO (or -2O48O) COLOR systems=&hB8OO (or -18432) SetVideoSeg &h7OOO 'sets video segment for virtual screens to &h7OOO SUBROUTINE: SetVideoSegPDQ NewVideoSeg% same as SetVideoSeg except that it sets the virtual video segment for programs linked with PDQ. This routine sets the value that is returned by VideoSegPDQ%. Note: This routine also updates the GPS library function VideoSeg%. example: SetVideoSegPDQ O 'resets the video segment to the REAL video segment 'MONO systems=&hBOOO (or -2O48O) COLOR systems=&hB8OO (or -18432) SetVideoSegPDQ &h7OOO 'sets video segment for virtual screens to &h7OOO ** Use only if LINKed with PDQ libraries ** Will not work inside QB editor/environment or with Quick-BASIC libraries SUBROUTINE: SetVideoSegQB NewVideoSeg% same as SetVideoSeg except that it sets the virtual video segment for programs linked with QB. It affects only LOCATE and PRINT (CLS uses a BIOS call). This routine sets the value that is returned by VideoSegQB%. Note: This routine also updates the GPS library function VideoSeg%. example: SetVideoSegQB O 'resets the video segment to the REAL video segment 'MONO systems=&hBOOO (or -2O48O) COLOR systems=&hB8OO (or -18432) SetVideoSegQB &h7OOO 'sets video segment for virtual screens to &h7OOO ** Use only if LINKed with Quick-BASIC libraries ** Will not work inside QB editor/environment or with PDQ libraries FUNCTION: VideoPtr% (Row%, Column%) Returns the pointer (offset) in video memory where Row%,Column% is located. It is useful whenever you wish to work directly with text-mode video memory. example: A% = VideoPtr%(12,4O) 'A% would be 1838 'same as A% = ( ( Row% - 1 ) * 16O ) + ( ( Column% - 1 ) * 2 ) FUNCTION: VideoSeg% The VideoSeg% function returns the current video memory segment for use with GPS library screen functions. example: VSeg% = VideoSeg% : DEF SEG=VSeg% : X% = PEEK(&hO5OO) 'see the SetVideoSeg subroutine FUNCTION: VideoSegPDQ% The VideoSeg% function returns the current video memory segment for use with PDQ library screen functions. example: VSegPDQ% = VideoSegPDQ% : DEF SEG=VSegPDQ% : X% = PEEK(&hO5OO) 'see the SetVideoSegPDQ subroutine ** Use only if LINKed with PDQ libraries ** Will not work inside QB editor/environment or with Quick-BASIC libraries FUNCTION: VideoSegQB% The VideoSeg% function returns the current video memory segment for use with Quick-BASIC's screen functions (LOCATE and PRINT). example: VSegQB% = VideoSegQB% : DEF SEG=VSegQB% : X% = PEEK(&hO5OO) 'see the SetVideoSegQB subroutine ** Use only if LINKed with Quick-BASIC libraries ** Will not work inside QB editor/environment or with PDQ libraries ┌─────────────────────────────────────────────────────────────────────────────┐ │ STRING FUNCTIONS │ └─────────────────────────────────────────────────────────────────────────────┘ Note: Do NOT use fixed-length strings with these functions !!! FUNCTION: AddCRLF$ (Text$) Returns the specified string with a <carriage-return><line-feed> combination appended to the end of it. example: X$=AddCRLF$(Y$) 'would be the same as X$=Y$+CHR$(13)+CHR$(1O) FUNCTION: AppLink$ Returns a 16-byte string containing the contents of the intra-application area which is located at OOOO:O4FO in the BIOS data area of low memory. This area can be used to hold data between CHAINed programs etc. (see SetAppLink) example: SetApplink "This is a test" A$=AppLink$ 'this would retrieve the string "This is a test " FUNCTION: AscMid% (Text$, Position%) Returns the ASCII value of the character located at Position% in the string Text$. This function performs the same task as ASC(MID$(Text$,Position%)) but it is faster. example: A% = AscMid%("ABCDEFGH",4) 'A% would be equal to 68 (ASCII value of D) FUNCTION: Bin$ (IntVal%) Returns a 16-byte string representing the unsigned binary value of IntVal%. example: A$=Bin$(&h1234) 'A$ would be "OOO1OO1OOO11O1OO" actual zeros are used (not letter O) ' └──┤└──┤└──┤└──┤ ' 1 2 3 4 hexadecimal 'The Replace subroutine could now be used to convert all zeros in A$ to 'the letter O in order to enhance readability. Replace A$,48,79 'replace all zeros (ASCII=48) with letter O (ASCII=79) FUNCTION: Center$ (Text$, LineWidth%) This function returns a string that is (LineWidth%) characters in length with Text$ centered inside it. Leading and/or trailing spaces are used to pad the string to the appropriate length. If Text$ is longer than LineWidth%, it is truncated to fit. example: A$=Center$("ABCD",7) 'A$ would be " ABCD " A$=Center$("ABCDE",7) 'A$ would be " ABCDE " A$=Center$("ABCDEF",7) 'A$ would be "ABCDEF " A$=Center$("ABCDEFG",7) 'A$ would be "ABCDEFG" FUNCTION: ChainLink$ Returns a 96-byte string containing the contents of the unused 96-byte area at the end of text-mode video memory which is located at VideoSeg%:OFAO. This area can be used to hold data between CHAINed programs etc. Note that this function must not be used in text modes utilizing more than 8O columns and 25 lines (such as 132 column modes or 43/5O/66 line modes). (see SetChainLink) example: SetChainlink "This is a test" A$=ChainLink$ 'this would retrieve a 96-byte string SUBROUTINE: ChgCase Text$ Changes the case of every alphabetic character in the Text$ string (i.e. lower-case becomes upper-case and upper-case becomes lower-case). example: Temp$="A-b-C-d-E-f" ChgCase Temp$ 'Temp$ would be changed to "a-B-c-D-e-F" NOTE: The string Text$ is changed (in place) and therefore MUST be a string variable !!! It can NOT be a literal string ("x") or a string function resultant (such as X$+Y$) !!! SUBROUTINE: ChgMid Text$, Position%, NewValue% Changes the ASCII value of the character at Position% in the string Text$ to the ASCII value specified by NewValue%. example: Text$="ABCDEFG" ChgMid Text$,3,32 'Text$ would be changed to "AB DEFG" NOTE: The string Text$ is changed (in place) and therefore MUST be a string variable !!! It can NOT be a literal string ("x") or a string function resultant (such as X$+Y$) !!! FUNCTION: InstrFwd% (StartAt%, SearchIn$, LookFor$) Returns the position of the first occurrence of LookFor$ in SearchIn$. The forward order search begins at position StartAt%. This function is identical to INSTR(StartAt%,SearchIn$,LookFor$) except that it returns zero if the LookFor$ string is null. (BASIC's INSTR function returns 1 - Why ? Who Knows ?) example: A%=INSTR (1,"ABC","") 'A%=1 A%=InstrFwd%(1,"ABC","") 'A%=O different from BASIC's INSTR A%=InstrFwd%(1,"ABC","B") 'A%=2 same as BASIC's INSTR FUNCTION: InstrRev% (StartAt%, SearchIn$, LookFor$) Returns the position of the LAST occurrence of LookFor$ in SearchIn$. The REVERSE-ORDER search begins at position StartAt%. If LookFor$ is null or if StartAt% is zero, the function returns zero. If StartAt% is negative or if StartAt% is greater than the length of SearchIn$, then StartAt% is set to the length of SearchIn$. example: 'separate the path from the filename PF$="C:\TEMP\MISC\ABC.DAT" 'path+file (assume we don't know form yet) X%=Larger%(InstrRev%(-1,PF$,"\"),InstrRev%(-1,PF$,":")) P$=LEFT$(PF$,X%) 'Here's the path F$=MID$(PF$,X%+1) 'and here's the filename FUNCTION: IntStr$ (IntVal%) Returns a forward-order 2-byte string from the 2-byte integer value IntVal%. This string can then be used in a FIELD or PUT statement etc. The forward-order means that the string can be sorted (unlike Quick-BASIC's MKI$ function). example: A$=IntStr$(&h1234) FUNCTION: IStr$ (IntVal%) Returns a string representation of the integer value (IntVal%) except that there is no leading space. It is exactly the same as LTRIM$(STR$(IntVal%)). FUNCTION: LJustify$ (Text$, LineWidth%) This function returns a string that is (LineWidth%) characters in length with Text$ left-justified inside it. Trailing spaces are used to pad the string to the appropriate length. If Text$ is longer than LineWidth%, it is truncated. example: A$=LJustify$("ABCD",5) 'A$ would be "ABCD " A$=LJustify$("ABCDEFG",5) 'A$ would be "ABCDE" FUNCTION: LongStr$ (LongVal&) Returns a forward-order 4-byte string from the 4-byte (long) integer value LongVal&. This string can then be used in a FIELD or PUT statement etc. The forward-order means that the string can be sorted (unlike Quick-BASIC's MKL$ function). example: A$=LongStr$(&h12345678) SUBROUTINE: LowerCase Text$ Changes any upper-case characters in Text$ to their lower-case equivalents. example: Text$="AbCdEf" LowerCase Text$ 'Text$ would be "abcdef" NOTE: The string Text$ is changed (in place) and therefore MUST be a string variable !!! It can NOT be a literal string ("x") or a string function resultant (such as X$+Y$) !!! FUNCTION: LStr$ (LongVal&) Returns a string representation of the long integer value (LongVal&) except that there is no leading space. It is exactly the same as LTRIM$(STR$(LongVal&)). SUBROUTINE: MemToString Text$,MemSeg%,MemPtr%,NumBytes% Copies a block of memory starting at MemSeg%:MemPtr% and having a length (in bytes) of NumBytes% into a variable-length string variable (e.g. Text$). example: MemToString Text$,&hB8OO,O,4OOO 'copy color screen to Text$ 'note: DGROUP string area is small so ' you should use sparingly. 'see also: StringToMem subroutine FUNCTION: NoMid$ (Text$, StartPos%, NumChars%) Returns the Text$ string with a section removed from it. The section that is removed begins at StartPos% and is NumChars% characters long. Essentially this function discards what BASIC's MID$ function keeps and vice versa. example: A$= MID$("ABCDEFGHIJK",4,3) 'A$ would be "DEF" A$=NoMid$("ABCDEFGHIJK",4,3) 'A$ would be "ABCGHIJK" FUNCTION: NoSegm$ (Text$, StartPos%, EndPos%) Returns the Text$ string with a section removed from it. The section that is removed begins at StartPos% and continues to EndPos%. example: A$=NoSegm$("ABCDEFGHIJK",3,7) 'A$ would be "ABHIJK" FUNCTION: NoSpace$ (Text$) Returns a string (from Text$) containing no imbedded spaces or nulls. example: A$=NoSpace$(" Testing 1 2 3 ") 'A$ would be "Testing123" FUNCTION: Repeat$ (Text$, NumTimes%) Returns a string containing Text$ repeated (NumTimes%) number of times. example: A$=Repeat$("Testing",3) 'A$ would be "TestingTestingTesting" SUBROUTINE: Replace Text$, OldChar%, NewChar% Converts all characters, having an ASCII value of OldChar%, in Text$ to the new ASCII value of NewChar%. example: Text$="This is a test" Replace Text$,32,45 'Text$ would be "This-is-a-test" space─┘ └─dash NOTE: The string Text$ is changed (in place) and therefore MUST be a string variable !!! It can NOT be a literal string ("x") or a string function resultant (such as X$+Y$) !!! FUNCTION: Reverse$ (Text$) Returns a string containing Text$ in reverse order. example: A$=Reverse$("ABCD") 'A$ would be "DCBA" FUNCTION: RJustify$ (Text$, LineWidth%) This function returns a string that is (LineWidth%) characters in length with Text$ right-justified inside it. Leading spaces are used to pad the string to the appropriate length. If Text$ is longer than LineWidth%, it is truncated. Note: If truncation is necessary, the RIGHT-most characters are preserved. example: A$=RJustify$("ABCD",5) 'A$ would be " ABCD" A$=RJustify$("ABCDEFG",5) 'A$ would be "CDEFG" FUNCTION: Segm$ (Text$, StartPos%, EndPos%) Returns the portion of Text$ which starts at StartPos% and ends at EndPos%. example: A$=Segm$("ABCDEFGHIJK",5,7) 'A$ would be "EFG" SUBROUTINE: SetChainLink Link$ Sets the contents of the unused 96-byte area at the end of text-mode video memory equal to the string value Link$. This area can be used to hold data between CHAINed programs etc. Note that this function must not be used in text modes utilizing more than 8O columns and 25 lines (such as 132 column modes or 43/5O/66 line modes). The area is padded with spaces to the right if Link$ is less than 96 bytes in length. (see ChainLink$) example: SetChainlink "This is a test" A$=ChainLink$ 'this would retrieve a 96-byte string SUBROUTINE: SetAppLink App$ Sets the contents of the 16-byte intra-application area equal to the specified string value App$. This area can hold data between CHAINed programs. Note that the area is padded with spaces to the right if App$ is less than 16 bytes in length. (see AppLink$) example: SetApplink "This is a test" A$=AppLink$ 'this would retrieve the string "This is a test " FUNCTION: StrChkSum& (Text$) Returns a long integer value representing the sum of all the bytes (ASCII values) in the Text$ string. example: A&=StrChkSum&("ABC") 'A& would be 198=65+66+67 SUBROUTINE: StringToMem Text$,MemSeg%,MemPtr%,NumBytes% Copies a variable-length string (e.g. Text$) into a block of memory starting at MemSeg%:MemPtr% and having a length (in bytes) of NumBytes%. example: StringToMem Text$,&hB8OO,O,4OOO 'copy Text$ to color screen 'note: DGROUP string area is small so you should use sparingly. ' If length of Text$ is larger than NumBytes%, then copying ' is stopped at count=NumBytes%. If length of Text$ is ' smaller than NumBytes%, spaces are used to pad additional memory 'see also: MemToString subroutine FUNCTION: StrInt% ( IntVal$ ) Returns a 2-byte integer value from the 2-byte string value IntVal$. Note that IntVal$ must have been made by the IntStr$ function because the StrInt% function requires a forward-order string operand. (see IntStr$) example: A$=IntStr$(1234%) A%=StrInt%(A$) 'A% would be 1234 FUNCTION: StrLong& ( IntVal$ ) Returns a 4-byte (long) integer value from the 4-byte string value IntVal$. Note that IntVal$ must have been made by the LongStr$ function because the StrLong& function requires a forward-order string operand. (see LongStr$) example: A$=LongStr$(123456789&) A&=StrLong(A$) 'A& would be 123456789 FUNCTION: Trim$ (Text$) Trims spaces from the left and right ends of Text$. It is the same as using RTRIM$(LTRIM$(Text$)). FUNCTION: TrimLCase$ (Text$) Trims spaces from the left and right ends of Text$ and also converts all alphabetic characters to lower case. It is the same as using LCASE$(RTRIM$(LTRIM$(Text$))). FUNCTION: TrimUCase$ (Text$) Trims spaces from the left and right ends of Text$ and also converts all alphabetic characters to upper case. It is the same as using UCASE$(RTRIM$(LTRIM$(Text$))). SUBROUTINE: UpperCase Text$ Changes any lower-case characters in Text$ to their upper-case equivalents. example: Text$="AbCdEf" UpperCase Text$ 'Text$ would be "ABCDEF" NOTE: The string Text$ is changed (in place) and therefore MUST be a string variable !!! It can NOT be a literal string ("x") or a string function resultant (such as X$+Y$) !!! SUBROUTINE: XORString Text$, XORValue% Performs the eXclusive-OR function (using XORValue%) on each character in the string value Text$. This makes it possible to implement a very simple encryption system. example: Text$="@@@" : XORString Text$,1 'Text$ would be changed to "AAA" XORString Text$,1 'Text$ would be changed back to "@@@" NOTE: The string Text$ is changed (in place) and therefore MUST be a string variable !!! It can NOT be a literal string ("x") or a string function resultant (such as X$+Y$) !!! ┌─────────────────────────────────────────────────────────────────────────────┐ │ SYSTEM / MISCELLANEOUS FUNCTIONS │ └─────────────────────────────────────────────────────────────────────────────┘ SUBROUTINE: ColdBoot Performs a COLD boot on the PC like pressing the Reset button. (checks memory) example: ColdBoot --or-- Call ColdBoot FUNCTION: DOSVersion% Returns the version of DOS currently in use on the PC (multiplied by 1OO). example: DV%=DOSVersion% 'if DOS version is 3.31 then DV%=331 'if DOS version is 5.OO then DV%=5OO SUBROUTINE: FormFeed Sends a form-feed (ascii 12) to the printer (PRN device usually LPT1:). example: FormFeed --or-- Call FormFeed SUBROUTINE: WarmBoot Performs a WARM boot on the PC like typing Ctrl-Alt-Del. (no memory check) example: WarmBoot --or-- Call WarmBoot APPENDIX A - KEYCODE VALUES RETURNED BY THE KEYBOARD FUNCTIONS (1O1-Key Keyboard) Note: The special function keys return (negative of scan_code) ┌─────┬─────┬─────┬─────┐ ┌─────┬─────┬─────┬─────┐ key │ │SHIFT│ CTRL│ ALT │ key │ │SHIFT│ CTRL│ ALT │ ┌───────┼─────┼─────┼─────┼─────┤ ┌───────┼─────┼─────┼─────┼─────┤ │ A │* 97 │ 65 │ 1 │ -3O │ │ ESC │ 27 │ 27 │ 27 │ ∙ │ │ B │ 98 │ 66 │ 2 │ -48 │ │ BKSP │ 8 │ 8 │ 127 │ ∙ │ │ C │ 99 │ 67 │ 3 │ -46 │ │ TAB │ 9 │ -15 │ ∙ │ ∙ │ │ D │ 1OO │ 68 │ 4 │ -32 │ │ SPACE │ 32 │ 32 │ 32 │ 32 │ │ E │ 1O1 │ 69 │ 5 │ -18 │ │ ENTER │ 13 │ 13 │ 1O │ ∙ │ │ F │ 1O2 │ 7O │ 6 │ -33 │ │ F1 │ -59 │ -84 │ -94 │-1O4 │ │ G │ 1O3 │ 71 │ 7 │ -34 │ │ F2 │ -6O │ -85 │ -95 │-1O5 │ │ H │ 1O4 │ 72 │ 8 │ -35 │ │ F3 │ -61 │ -86 │ -96 │-1O6 │ │ I │ 1O5 │ 73 │ 9 │ -23 │ │ F4 │ -62 │ -87 │ -97 │-1O7 │ │ J │ 1O6 │ 74 │ 1O │ -36 │ │ F5 │ -63 │ -88 │ -98 │-1O8 │ │ K │ 1O7 │ 75 │ 11 │ -37 │ │ F6 │ -64 │ -89 │ -99 │-1O9 │ │ L │ 1O8 │ 76 │ 12 │ -38 │ │ F7 │ -65 │ -9O │-1OO │-11O │ │ M │ 1O9 │ 77 │ 13 │ -5O │ │ F8 │ -66 │ -91 │-1O1 │-111 │ │ N │ 11O │ 78 │ 14 │ -49 │ │ F9 │ -67 │ -92 │-1O2 │-112 │ │ O │ 111 │ 79 │ 15 │ -24 │ │ F1O │ -68 │ -93 │-1O3 │-113 │ │ P │ 112 │ 8O │ 16 │ -25 │ │ F11 │ ∙ │ ∙ │ ∙ │ ∙ │ │ Q │ 113 │ 81 │ 17 │ -16 │ │ F12 │ ∙ │ ∙ │ ∙ │ ∙ │ │ R │ 114 │ 82 │ 18 │ -19 │ │ UP │ -72 │ -72 │ ∙ │ ∙ │ │ S │ 115 │ 83 │ 19 │ -31 │ │ DOWN │ -8O │ -8O │ ∙ │ ∙ │ │ T │ 116 │ 84 │ 2O │ -2O │ │ LEFT │ -75 │ -75 │-115 │ ∙ │ │ U │ 117 │ 85 │ 21 │ -22 │ │ RIGHT │ -77 │ -77 │-116 │ ∙ │ │ V │ 118 │ 86 │ 22 │ -47 │ │ INS │ -82 │ -82 │ ∙ │ ∙ │ │ W │ 119 │ 87 │ 23 │ -17 │ │ DEL │ -83 │ -83 │ ∙ │ ∙ │ │ X │ 12O │ 88 │ 24 │ -45 │ │ HOME │ -71 │ -71 │-119 │ ∙ │ │ Y │ 121 │ 89 │ 25 │ -21 │ │ END │ -79 │ -79 │-117 │ ∙ │ │ Z │ 122 │ 9O │ 26 │ -44 │ │ PGUP │ -73 │ -73 │ 1O1 │ ∙ │ │ O or )│ 48 │ 41 │ ∙ │-129 │ │ PGDN │ -81 │ -81 │-118 │ ∙ │ │ 1 or !│ 49 │ 33 │ ∙ │-12O │ │ - or _│ 45 │ 95 │ 31 │-13O │ │ 2 or @│ 5O │ 64 │ -3 │-121 │ │ + or =│ 61 │ 43 │ ∙ │-131 │ │ 3 or #│ 51 │ 35 │ ∙ │-122 │ │ | or \│ 92 │ 124 │ 28 │ ∙ │ │ 4 or $│ 52 │ 36 │ ∙ │-123 │ │ { or [│ 91 │ 123 │ 27 │ ∙ │ │ 5 or %│ 53 │ 37 │ ∙ │-124 │ │ ] or }│ 93 │ 125 │ 29 │ ∙ │ │ 6 or ^│ 54 │ 94 │ 3O │-125 │ │ : or ;│ 59 │ 58 │ ∙ │ ∙ │ │ 7 or &│ 55 │ 38 │ ∙ │-126 │ │ " or '│ 39 │ 34 │ ∙ │ ∙ │ │ 8 or *│ 56 │ 42 │ ∙ │-127 │ │ < or ,│ 44 │ 6O │ ∙ │ ∙ │ │ 9 or (│ 57 │ 4O │ ∙ │-128 │ │ > or .│ 46 │ 62 │ ∙ │ ∙ │ │ ` or ~│ 96 │ 126 │ ∙ │ ∙ │ │ ? or /│ 47 │ 63 │ ∙ │ ∙ │ └───────┴─────┴─────┴─────┴─────┘ └───────┴─────┴─────┴─────┴─────┘ * indicates keycode for lower-case alphabetic characters for example: a=97 A=65 z=122 Z=9O ┌──────────────────────────────────────────────────────────────────────────────┐ │ APPENDIX B FADES for the ScreenFade Subroutine │ ├──────────────────┬┬──────────────────┬┬──────────────────┬┬──────────────────┤ │ O Quick ││19 Spiral CW In ││38 Wipe V Close ││57 Circ Sweep Down│ │ 1 Fizz ││2O Spiral CW Out ││39 Half Wipe V U/D││58 Circ Sweep Up │ │ 2 Melt Down ││21 Spiral CCW In ││4O Half Wipe V D/U││59 Radar CW │ │ 3 Melt Up ││22 Spiral CCW Out ││41 Half Wipe H L/R││6O Radar CCW │ │ 4 Liquid Flow Dn ││23 Mult Sp CW In ││42 Half Wipe H R/L││61 Louver H Large │ │ 5 Liquid Flow Up ││24 Mult Sp CW Out ││43 Checker Down ││62 Louver H Small │ │ 6 Quarters - CW ││25 Mult Sp CCW In ││44 Checker Up ││63 Louver V Large │ │ 7 Quarters - CCW ││26 Mult Sp CCW Out││45 Diagonal Right ││64 Louver V Small │ │ 8 Quarters - Alt ││27 Wipe Down ││46 Diagonal Left ││ │ │ 9 Blks Random Lg ││28 Wipe Up ││47 Chckr Lvr 1step││ │ │1O Blks Random Sm ││29 Wipe Right ││48 Chckr Lvr 2step││ │ │11 Zigzag H Lg Rt ││3O Wipe Left ││49 Diagonal Lvr R ││ │ │12 Zigzag H Lg Lft││31 Curtain H Open ││5O Diagonal Lvr L ││ │ │13 Zigzag H Sm Rt ││32 Curtain H Close││51 Page Feed Down ││ │ │14 Zigzag H Sm Lft││33 Curtain V Open ││52 Page Feed Up ││ │ │15 Zigzag V Down ││34 Curtain V Close││53 Page Feed Right││ │ │16 Zigzag V Up ││35 Wipe H Open ││54 Page Feed Left ││255 selects a │ │17 Orifice Open ││36 Wipe H Close ││55 Circ Sweep CW ││ random fade │ │18 Orifice Close ││37 Wipe V Open ││56 Circ Sweep CCW ││ from this list│ └──────────────────┴┴──────────────────┴┴──────────────────┴┴──────────────────┘ Note: The program FADES.EXE will demonstrate each of these fades.